RSX-11M-—PLUS and Micro/RSX 
I/O Operations 


Reference Manual 
Order No. AA-JS16A-TC 


RSX-11M-PLUS Version 4.0 
Micro/RSX Version 4.0 


Digital Equipment Corporation Maynard, Massachusetts 


ea ee Ss 
First Printing, December 1975 

Revised, December 1976 

Revised, December 1977 

Revised, June 1979 

Revised, June 1981 

Revised, June 1985 

Revised, September 1987 


The information in this document is subject to change without notice and should not be 
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation 
assumes no responsibility for any errors that may appear in this document. 


The software described in this document is furnished under a license and may be used or copied 
only in accordance with the terms of such license. 


No responsibility is assumed for the use or reliability of software on equipment that is not 
supplied by Digital Equipment Corporation or its affiliated companies. 


Copyright ©1975, 1976, 1977, 1979, 1981, 1985, 1987 by Digital Equipment Corporation 


All Rights Reserved. 
Printed in U.S.A. 


The postpaid READER'S COMMENTS form on the last page of this document requests the 
user’s critical evaluation to assist in preparing future documentation. 


The following are trademarks of Digital Equipment Corporation: 


DEC EduSystem UNIBUS 
DEC/CMS IAS VAX 
DEC/MMS MASSBUS VAXcluster 
DECnet MicroPDP-11 VMS 
DECsystem—10 Micro/RSX VT 
DECSYSTEM-20 PDP 

DECUS PDT 

DECwriter RSTS dligiijtialll 
DIBOL RSX 


ZK3079 


HOW TO ORDER ADDITIONAL DOCUMENTATION 
DIRECT MAIL ORDERS 


USA & PUERTO RICO* CANADA INTERNATIONAL 

Digital Equipment Corporation Digital Equipment Digital Equipment Corporation 
of Canada Ltd. PSG Business Manager 

P.O. Box CS2008 100 Herzberg Road c/o Digital’s local subsidiary 

Nashua, New Hampshire 03061 Kanata, Ontario K2K 2A6é or approved distributor 


Attn: Direct Order Desk 


In Continental USA and Puerto Rico cail 800-258-1710. 

In New Hampshire, Alaska, and Hawaii call 603-884-6660. 

In Canada call 800-267-6215. 

* any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575). 


Internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment Corporation, Westminster, 
Massachusetts 01473. 


a 
This document was prepared using an in-house documentation production system. All page composition and make-up was 
performed by 1X. the typesetting system developed by Donald E. Knuth at Stanford University. EX is a trademark of the 
American Mathematical Society. 


Contents 
Rs i re Pe a ed 


Preface XV 
a Se 


summary of Technical Changes xxi 
a 


Chapter 1 File Control Services 
i 


1.1 
1.2 
1.3 


1.4 
1.5 


1.6 
1.7 


1.8 
1.9 


Key Terms Used Throughout This Manual....................0----0-2... 1-2 
Important FCS Characteristics... 2... eee eee eee. 1-4 
BOS Data SU CTeSs hss a5 a al Vive oleh Biwi a A ateane deh ihe eos dade ace os 1-5 
1.3.1 Pile Descriptor BIOCK 2. 20a aha wiley lad Saba a Se nlomidk fg keene: 1-5 
1.3.2 Data-Set Descriptor and Default Filename Block ..................... 1-5 
1.3.3 File, Storage Repionig oad gig 9 x See BR awed deg RR A ge oe ys whee ce 1-6 
Fille: Access MCENOS oo i254: 8% ata dD posit Puterdl Drones ark Nant a oO datas, Sted Ui aoa 1-6 
Data Formats for File-Structured Devices... 2.000.000 00 cece eee eee eee eee 1-6 
1.5.1 Data Formats for ANSI Magnetic Tape .....................-.2... 1-8 
Block 170) Operations, 32 aad! cinh treet Sess, ean ddl Sees doth uae eacare te Sedu igh the, 1-8 
Record 1. -Operauons: x00: 44h. J oShag i dickut Od @ GUY ae Ra SG Soaeay 8 S51 tee Louk 1-8 
1.7.1 Record I/O Data-Transfer Modes... .. 0.0.0.0... 000-0000 e eee ee 1-10 
1.7.2 Multibuffering for Record I/O... 2.2... 000.020.0000 0c eee eee 1-11 

1.7.2.1 Multibuffering Performance .........00.0.0..000000 0000000. 1-12 
1.7.3 Big Buifering for ‘Record 1/ Oss. 95 igo 54k Avk © ea We eee enh 1-12 
shiared Access’t0 FHS a. gaudy Bag a PeeWee auth dew no eh chy Reed outed s 1-13 
File Specihicatiort Syntax: %. svcd iit adarstns & ais Beene ig ek acy of beh alaeig dating acted ae 2 1-14 
1.9.1 PDONICE Aiea See eras che cheanil WS ile ani, Moe te ay fet tla yee 1-15 
1.9.2 DUTCH ek tary Siete had Soca, Be Sees BATA A ite aise aa aah haghiin Lop seed tas 1-15 
1.9.3 IAIN ES cielsie, ete Mt OU hs ote tate Seg asc ath eee hie eo te Booey ty 1-16 
1.9.4 MY BO" Bie A eacteca tad tcprae dah a6 ta aoc ence leg Pele Geeta te le ange dots ot lone Se ie Bc dea tae 1-16 
1.9.5 WETSIOM “ther Spee toed ihe coe e eae timid, Mer tee soot oh Boe tas 1-16 
ANSI Magnetic Tape File Specification Syntax ...........0000 0000 cee eee. 1-17 
PbO?» OVI e eee? Shas het got wale aaa et ciris ac as Me Goa pete TAA Aig lene Oo ek 1-17 
PO 2 WMCCHORY: cece Seatt cere a bie wins oh gti BAe aN ENE ee 5 tall Se ene | 1-17 


itt 


1.11 
1.12 


1.13 


1.103. Quoted Sting 2....0 49 Reed eee eA Ge DERE E SE EERE REE es 1-18 


1.404: VetsIOR seh eis kee BER EPR EE PRESS LES ee See ee 1-18 
1.10.4.1 Example Magnetic Tape File Specification .... 6-1. - +s essere rere 1-18 
Generation of a Full File Specification... 6. es 1-18 
Logical Names 2505.45 o.o4 0h al Gok PPI RE EE OE ERT EO pe EE Re 1-19 
1.12.1. Using Logical Names for Program Input and Output ...-.----+--- +555 1-20 
1.12.1.1 Logical Name Tables... 60-20 ee ee ees 1-20 
1.12.1.2 Specifying Logical Names ...- 6-0 eee et ees 1-20 
Routines Included in FCSRES .. 1... 2. ee 1-21 


Chapter 2 Preparing for |/O 


2.1 
2.2 
2.3 


2.4 


2.9 


2.6 


2.7 


2.8 


2.9 


General Information .... 2-2... e eee eee ett tet ene 2-1 
‘MCALL Directive—Listing Names of Required Macro Definitions........-++-+--+--: 2-2 
File Descriptor Block... 6.6 ee ee ee te eee eens 2-3 
2.3.1 Assembly-Time FDB Initialization Macros .....--- +e +e eee ttt es 2-3 

2.3.1.1 FDBDF$—Allocate File Descriptor Block .... 2... -. ee eee 2-5 

2.3.1.2 FDAT$A—lInitialize File Attribute Section of FDB..........-----+-: 2-5 

2.3.1.3 FDRC$A—lInitialize Record Access Section of FOB ..........-+----- 2-9 

2.3.1.4 FDBK$A—Initialize Block Access Section of FDB ......-...-+4--- 2-11 

2.3.1.5 FDOP$A—Initialize File-Open Section of FDB..........----5--- 2-13 

2.3.1.6 FDBF$A—Initialize Block Buffer Section of FDB..........-.-5---: 2-17 
2.3.2 Run-Time FDB Initialization Macros... 66. 0 es 2-20 

2.3.2.1 Run-Time FDB Macro Exceptions ..... 1... 2-2 eee eee eee ee 2-21 

2.3.2.2 Specifying the FDB Address in Run-Time Macros ........-.-+++:- 2-23 
Global Versus Local Definitions for FDB Offsets .... 6.0... eee eee eee eee 2-24 
2.4.1 Specifying Global Symbols in the Source Code... 2... +0 eer eres 2-24 
2.4.2 Defining FDB Offsets and Bit Values Locally .....- +--+ seer eeee 2-25 
Creating File Specifications Within Your Program ...... 0 eee ees 2-26 
2.5.1 Data-Set Descriptor... 6... ee te 2-27 
2.5.2 Default Filename Block—NMBLK$ Macro .... 2... eee eee ee ees 2-29 
2.5.3 Dynamic Processing of File Specifications... .--- +--+ +e t etree 2-32 
Optimizing File Access . 6... ee et tes 2-32 
2.6.1 Initializing the Filename Block as a Function of OPEN$X: 5 i cee ewe rs 2-33 
2.6.2 Manually Initializing the Filename Block... 1.6... ee ee eee ees 2-34 
Initializing the File Storage Region... 2... -- eet ee 2-35 
2.7.1 FSRSZ$—Initialize FSR at Assembly Time... 2... - 2 eee ee es 2-35 
2.7.2 FINIT$—Initialize FSR at Run Time... 1.2... ee ee es 2-37 
Increasing the Size of the File Storage Region... . 6... eee rere eres 2-38 
2.8.1 FSR Extension Procedures for MACRO-11 Programs .......---.++++55 2-38 
2.8.2 FSR Extension Procedures for FORTRAN Programs .... 1... eee eee 2-39 
Coordinating I/O Operations ... 1... 66 ee es 2-39 


2.9.1 Event Ela gs 2 iets cie 8 Sian bis conic eet ee AS eee Yolande om exo 2-40 


2.9.2 F/O Stats BICC <n ch a tester nde h ae aly ek alge debia acl tl bod og dees oan 2-41 
2.9.3 AST Service ROWHNG sy oso e Sigg hae yess a dleog vnc aca 4 ated net’ hovers te hs 2-42 
2.9.4 Bloel BOCAS Hal ay a.6 Geeta ieee Malas GS Su chiy Ce 0 clients elie 2-43 
2.9.5 Error Codes Related to Shared Files and Block LOCKING 6.4.55. 35 bk sae wl 2-45 


Chapter 3 File-Processing Macros 


3.1 


3.2 
3.3 
3.4 
3.5 
3.6 


3.7 
3.8 
3.9 


3.10 
3.11 
3.12 


3.13 
3.14 
3.15 


3.16 


3.17 


OPEN$x—Generalized Open Macro... 20... 2... eee eee. 3-3 
3.1.1 Format of Generalized OPEN$x Macro ......................-.... 3-5 
3.1.2 FDB Requirements for Generalized OPEN$x Macro ................... 3-8 
OPNS$x—Open File for Shared Access... 22... 0000... 000-0 000-000-220... 3-11 
OPNT$W—Create and Open Temporary File................0...0-...... 3-12 
OPNT$D—Create and Open Temporary File and Mark for Deletion ............. 3-13 
OFID$x—Open File by FileID «6.0.2... ee 3-13 
OFNB$x—Open File by Filename Block ...................0..00---.... 3-14 
3.6.1 Data-Set Descriptor or Default Filename Block .........,........... 3-15 
3.6.2 Default Filename Block Only ........................ tess ange eat 3-15 
OPEN$—Generalized Open for Specifying File Access ................0....., 3-16 
CLOSE$—Close Specified File... 2... eee. 3-17 
GET$—Read Logical Record... 2... eee ee. 3-18 
3.9.1 Format of GET$ Macro... 2.2... eee 3-19 
3:9:2 The FDB Relevant to GET$ Operations .......................... 3-20 

3.9.2.1 GET$ Operations in Move Mode ....................-..... 3-21 

3.9.2.2 GET$ Operations in Locate Mode .......................... 3-21 
GET$R—Read Logical Record in Random Mode ...................00..... 3-22 
GET$S—Read Logical Record in Sequential Mode... ....................... 3-23 
BUTS =Write Logical Record... aa 4% fe) 6a eects ala ee yu lat 4 Ok be cs enw ee 3-24 
3.12.1 Format of PUT$ Macro... 2... eee eee, 3-24 
3.12.2 The FDB Relevant to PUT$ Operations.......................... 3-25 

3.12.2.1 PUT$ Operations in Move Mode .......................... 3-26 

3.12.2.2 PUT$ Operations in Locate Mode ..................-00..... 3-26 
PUT$R—Write Logical Record in Random Mode.......................... 3-28 
PUT$S—Write Logical Record in Sequential Mode... 22... 0. eee ce eee 3-29 
READ$—Read Virtual Block .. 2.2... 2. ccc eee. 3-30 
3.15.1 Format of READ$ Macro... 02.2... 2. eee 3-30 
3.15.2 The FDB Relevant to READ$ Operationts ce tata: peiuh coed ood Be bok @ Yus-pah dese 3-33 
WRITES Wate Virtital BIO sox. Seve teeta. ding'e eb ahateed Bary Ga ae pace doen 3-33 
3.16.1 Format of WRITE$ Macro.... 2.2.2... ee eee. 3-33 
3.16.2 The FDB Relevant to WRITE$ Operations ........................ 3-36 
WAIT$—Wait-for Block I/O Completion ....................-----02.... 3-36 
3.17.1 Format of WAIT$ Macro .... 2.2... eee 3-36 


3.18 DELET$—Delete Specified File .... 1... +. se eee tres 3-38 


Chapter 4 File Control Routines 


4.1 
4.2 


4.3 


4.4 


4.5 


4.6 


4.7 


4.8 


4.9 


Calling File Control Routines ©... 6. eee eet tsetse 4-2 
Default Directory String Routines... 1.26.0 eee eee tts 4-3 
4.2.1 RDFDR—Read $$FSR2 Default Directory String Descriptor.......---+-++: 4-3 
4.2.2 'WDFEDR—Write New $$FSR2 Default Directory String Descriptor .......-- 4-3 
Default UIC Routines Vs ois eee eee eRs PARR ee aE RE eRe ieee eet 4-4 
4.3.1 RDFUI—Read Default UIC 26... ee ee ets 4-4 
4.3.2 'WDFUI—Write Default UIC. ©... 6. ts 4-4 
Default File Protection Word Routines. ©... 2... eee eet 4-5 
4.4.1 -RDFFP—Read $$FSR2 Default File Protection Word ....---- +--+ eee: 4-5 
4.4.2 'WDFFP—Write New $$FSR2 Default File Protection Word ....-.-+------ 4-6 
File Owner Word Routines... 0... ee ete ss 4-6 
4.5.1 -RFOWN—Read $$FSR2 File Owner Word .....-- eee ere res 4-7 
4.5.2 -WFOWN—Write New $$FSR2 File Owner Word ...-.. +--+ e terre 4-7 
ASCII/Binary UIC Conversion Routines ..- 2. +22 eet rrr setts 4-7 
4.6.1 -ASCPP—Convert ASCII Directory String to Equivalent Binary WIC. ee Soe tie 4-7 
4.6.2 -PPASC—Convert UIC to ASCII Directory String ..-.-- eee tees 4-8 
Filename Block Roubines 44, 4.4.¢¢0-.4 ee ise a ee Ee PEE ERE eR ee 4-8 
4.7.1 Logical Name Translation... .. 6-62 este tens 4-8 

4.7.1.1 Iterative Translation... 6.6... eee tte 4-9 

4.7.1.2 Logical Translation Process ....- +--+ 2+ errr tts 4-10 
4.7.2 -PARSE—Fill in All File Name Information ....--- +--+ seer reece 4-10 

4.7.2.1 Device and Unit Information .... 6... ++ eee ts 4-12 

4.7.2.2 Directory Identification Information... 1... + +++ sere etre 4-13 

4.7.2.3 File Name, File Type, and File Version Information. ..--..---+++++- 4-14 

4.7.2.4 Using the FDB Extension for Logical Names ....-- 0-22 eer 4-14 

4.7.2.5. Other Filename Block Information... ..-. 6. see eer tts 4-15 

4.7.2.6 .EXPLG Module (Expand Logical)... 6. +--+ eee errr te 4-15 
4.7.3 PRSDV—Fill in Device and Unit Information Only ..... 6. +--+ seers 4-15 
4.7.4 PRSDI--Fill in Directory Identification Information Only .....--+ +++ ++ 4-15 
4.7.5 PRSFN—Fill in File Name, File Type, and File Version Only ......----- 4-16 
4.7.6 ASLUN=-Assion LUN .j)taggoe att ett He etn e Pe Pre Teese 4-16 
Directory Entry Routines... 6. - eee eee teeter eens 4-16 
4.8.1 -FIND—Locate Directory Entry ©... 2-2-6 eee eee et ttt ts 4-16 
4.8.2 ENTER—Insert Directory Entry ... 6... 2-0 seer ret rts 4-19 
4.8.3 -REMOV—Delete Directory Entry ...- 2-2. eee errs 4-19 
Filename Block Routines .. 0.0. etter tne 4-19 
4.9.1 GTDIR—Insert Directory Information in Filename Block. .......--+-+-- 4-19 
4.9.2 CTDID—Insert Default Directory Information in Filename Block ......--. 4-20 


vi 


SO See hace odd patsy cs ace 4-21 
4.10.1 .POINT—Position File to Specified i or eee 4-21 
4.10.2 .POSRC—Position eS PPS RECO aha act ne wcenigss 4-22 
4.10.3 .MARK—Save Position Information COMEAE OF PIS ok Gyo 2 sade ue eee ee, 4-22 
4.10.4 .POSIT—Return Specified Record Position Information......00 000 4-23 

4.11 .XQIO—Queue ee ues locas wavae 4 4-23 

4.12 .RENAM—Rename Bee aD Serer scat gan eee a 4-23 

4.13 EXTND—File es tee te erage 4-24 

4.14 .TRNCL—File Sige ery eee CERI On ban 4-25 

4.15 File Deletion oh eG etnies ee aan ee ok 4-26 
4.15.1 .MRKDL—Mark Temporary File for DSTO ie artes oa tm eae pe dv a 4-26 
4.15.2 .DLFNB—Delete oe EBON, C5 coy oriat Vex te ea 4-26 

4.16 .CTRL—Device He age Smid ata ee 4-27 

4.17 .FLUSH—Buffer Flush Pee eM ete ION Ae ea ue tot oe 4-28 
4.17.1 Purpose of the ee ROR tae eat ag hoe ceo 4-28 
4.17.2. When .FLUSH ee Me Cretan Une 4-28 
4.17.3 Performance Considerations DONE PLUSH: Sept ecet ae, ce alia: 4-28 
4.17.4 Using the FLUSH se ee en manne eek 4-28 

Chapter 5 File Structures 

5.1. Disk and DECtape File Structure Oy SRR ad oh patil oh taste. ti 5-1 
5.1.1 eae ee 5-2 
5.1.2 see et wy Ue ina ea sci 5-2 
5.1.3 tite en ee 5-3 
5.1.4 ila ge Oe 5-4 

5.2 Magnetic Tape File hime Grae ete Oe Le 5-5 
5.2.1 Access to ee Oe cheesy Ae sanet eae 5-5 
5.2.2 ee ieee 5-6 
5.2.3 Positioning to the Next Pipe POU OM Saag NarbaaaNs wih was an nti 5-6 
5.2.4 Ge eee oS 5-7 
5.2.5 Pe eee oticcmam stacy ee 5-7 
5.2.6 Pe On ett aac 5-7 
5.2.7 Examples of Magnetic Tape NBS GREE og Aceh Soy eek Bh <n 5-8 

9.2.7.1 Examples of OPEN$W Macro-11 Statements to Create a New Ble nolan ye 5-8 
5.2.7.2 Examples of OPEN$R Macro-11 Statements to Reada File... 5-9 
5.2.7.3. Examples of CLOSE$ Macro-11 SENSES an sac S co tends ghtns 5-10 


5.2.7.4 Combined Examples of OPEN$ and CLOSE$ Macro-11 Statements ... . 5-10 


vil 


6.1 


6.2 


7.1 


7.2 


7.3 
7.4 


Chapter 6 Co 


Chapter 7 The T 


mmand Line Processing 


Get Command Line (GEM) Routine; ¢s4 Sreca ee  eee T AP 


6.1.1 GCMLB$—Allocate and Initialize GCML Control Block ©... 0 eset 6-3 
6.1.2 GCMLD$—Define GCML Control Block Offsets and Bit Values ..- +--+ 077° 6-5 
6.1.3 GCML Routine RancTine Macros fay Se aac HERO RAE A 6-9 
6.1.3.1 GCML$—Get Command Line Mago ss aed etsy ete he 6-9 
6.1.3.2 RCML$—Reset Indirect Command File Scan Macro .--- ett 6-11 
6.1.3.3 CCML$—Close Current Command File Matio.ck Sheva eee eer 6-12 
6.1.4 POM Ussee Considerations ies iad ean ere FETT 6-13 
Command String Interpreter BoNiheh Leen e pe ee ERE A 6-13 
6.2.1 CSI$—Define CSI Control Block Offsets and Bit Values Macro... +--+ 007" 6-14 
6.2.2 CSI$ Macro Control Block Offset and Bit Value Definitions ..-- +--+ 770° ° 6-14 
6.2.3 Soe auntie Macios te sateen eer te 6-18 
6.2.3.1 CSI$1—Command Syntax Analyzeres ).c sss 280 pre eee 6-18 
6.2.3.2 CS1$2—Command Semantic Parser Macro «-- se 6-19 
6.2.3.3 csi¢4—Command Semantic Parser Macro .--- sr 6-21 
6.2.4 CSI Switch Definition A tn CS ee oe a 6-22 
6.2.4.1 CSI$SW—Create Switch Descriptor Table Entry Macro .---+-s0 00 6-22 
6.2.4.2 CSI$SV—Create Switch Value Descriptor Table Entry Macro .-----+ °° 6-27 
6.2.4.3 CSI$ND—Define End of Descriptor Table... --- sss 6-29 


able-Driven Parser (TPARS) 


Coding TPARS Source Discanieau area ieteu eee Pet oj 3a. 


7.1.1 TPARS Macros—ISTAT$, STATE$, and TRANS .-----s 7-1 
7.1.1.1 ISTATS Macro—Initialize the State Tables ba SG ee pte AE 7-2 
7.1.1.2 STATES Macro—Defining a Syntax flement’ 2.2. seeker eer eee 7-2 
7.1.1.3 TRANS Macro—Defining a Transition ©... 00ers 7-3 
7.1.2 Action Routines and BuiitsIn Variables «hyo sre gerne ee TT 7-5 
7.1.2.1 TPARS Built-In VRAAbIee Bak Bae SR. 7-5 
7.1.2.2 Calling Action RGeS gE aa SERIA ae PS Ee 7-5 
7.1.2.3 Using Action Routines to Reject a Transco) .<4 sos EASE 7-6 
7.1.2.4 Optional Debug Routine for RSX-11 Users .--- errr 7-6 
7.1.3 Soins Cuieorecone: ca amen maw Pape ROE oe 7-6 
General Coding Pe Hol ianeraa ti SRM Oe ree eso 7-7 
7.2.1 Suggested Arrangement of Syntax Types in a State Table... ee rete 7-7 
7.2.2 Ignoring Blanks and Tabs in a Command Lin a..¢.e 5 ees pee eee 7-8 
7.2.3. Entering Special pn mr ee a ae Bee 7-8 
7.2.4 Recognition of Ge Hitlers naans gcse SRT E SPEEA 7-9 
Program Sections Ecnerated By TPARS Macros ‘apa vate SSO SS 7-9 
Se ine TEARS osu c sua sa mags ey ee TEE TS 7-11 


viii 


7.4.1 Register Usage and Calling Conventions ......................... 


7.4.2 Using the Options Word ............00000.000....0........, 
7.5 How to Generate a Parser Program Using TPARS ......................... 
7.6 Programming Examples... 2.6... eee cece cece ee. 
7.6.1 Parsing a UFD Command Line ............................... 
7.6.2 Using Subexpressions and Rejecting Transitions .................... 
7.6.3 Using Subexpressions to Parse Complex Command Lines .............. 


Chapter 8 Spooling 
eee 


Boe SPRINTS Maco ss. spa inky Sidney adh VEU oh iols dg Ph ad, paatalta’s (he! aashias ae 
Bas” CP RINT SUDHOUING? XW Nie Win nod ne Malay eg abet wis he huh cng, nee, 
8.2.1 Opening a File on Disk and Using the PRINT Command .............. 
8.2.2 Opening a Fule*O0 SEP 2.5 ia aidan ei oh oh ee ee ded ble eee 
Bree: EMO PUA NING ih tig ids, dP G Unite ables nd Re ead enike oo uetucne 2 ee 


Appendix A_ File Descriptor Block 


Appendix B_ Filename Block 


Appendix C_ File Header Block 


Soh <PICAGEL AUER aides gia hola at Oo Scadl tele ree St chy hen Oe fasta! Shi ra 
Rie, AMPOUNGRHOR ATE gag Pisce State tented ee Bh Wa ance eit aa hei bate ane 
BE, SMAI ae Vie sats hose SN Riad ae elt ipods 8 8 ead Seacioe tae o 


Appendix D_ Statistics Block 


Appendix E Index File Format 


Ets -Bootstiap BlOck: fives tai deli ae yaad att itt dae Sd lth ae Meo teh ys © 
Bie) SIOMENBIOGK t soct gs Wletiysla Giiw a ale nls 8 na tata a: lt en, Soc Kda fe vic, Ye, 
Bes AMGEN PUS Bi Map aah wisice die cih Y py IRE ata cae Abele osha nya. Chaps oy 
E.4 Predefined File Header Blocks... 2... 0... eve eee cece eee, 


Appendix F Summary of 1/O-Related System Directives 


Appendix G Support of ANSI Magnetic Tape Standard 


G.1 Volume and File Labels .. 2.2... eee eee 
G.1.1 Volume Label Format... 6.0.2. 
G.1.1.1 Contents of Owner Identification Field... 6-1 ee ere tes 
CAD Weer Volume Labels: on: Le catee st PEAS CR ERE OOS EEE ETD 
C13 File Header Labels 2... 2. ee eee eee ee eee et eee eee 
G.1.3.1 File Identifier Processing by Files-1] --- 1. ++ eee eer rere 
G.1.4 _End-of-Volume Labels... 6-2-0 seer eet 
G1S File Trailer Labels. cee sles oe ee oe eR ees SE een 
C16 ° UserFile Labels ey. oi Bw Re eS OEE ES Aa ere see ee ee 
C5 Pile Structiives 6.04. cee Sas PASSES SE SPY EAE RE EOE ESS 
G.2.1 File Structure Format... 6... eee ts 
GB. ‘End-of-Tlape Handling ii: 5.+ Seen sah Peg ee eS ee ee Poe ye 
G.4 ANSI Magnetic Tape File Header Block (FCS Compatible)... ..--- e+ eee tes 
G.5 The Magnetic Tape Control Task... -.- eer 
CS. “MAC Command Examples. 2060 i¢ 2 ea ees ee Bek ee ert ae 
C.5.2 MAG Command Error Messages .--- +--+ seer 
Ge ‘Ualsbeled Tape: scov Law ns wee SEES RE REESE EERE EEE R IAT SS 
G.6.1 Block Size on Tapes Mounted /NOLABEL ....-- +--+ errr 
G62. “Tape Positioning: ce anya sede e FG BAe pe STA ee Eee ES 
G.6.3 Specifying File Attributes... 6-1. eee errs 
G64 “Tape Translation <2 eys sys ekg ete PS ee Pee ets 
G.6.5 Example of EBCDIC Translation Tables... tes 
G.7_ Example Using an Indirect Command File to Read a Tape... .---- eee errs 


Appendix H QIOS Interface to the ACPs 


H.1 How to Use the ACP QIO$ Functions ...-- seers 
Hala - Creating a File) 2...64.py 0) G24 eye coe ao ae ee Pee Es 
HAD “Openings Filey sous iste ee Sree ee ey a Eee Oe 
WikGe iClosing aula. pout e gle tA PS ESA ee Bee RES OE REE ES 
H.i4 Extending a File... 6.0. see ee ee ee te ee ee eens 
His. “WWeleting ale iic5. ee ay ee he OS REAR E PE POET E TS 
H.2 Errors Returned by the File Processors ...- +--+ ss srr rrr 
H.3  QIO$ Parameter List Format... 6... eee eee rete testes 
H.3.1 File Identification Block .. 6... 0s eee eee ss 


H.3.2 THe ATDUE IGE & 2 lac a toe hg tbe Bitter ah ate Pode teak nity sii ety ta phot th ae, H-7 


Hid.2, 1) “Phe Attibute Vy pee wis: gua nage baw kaon d ald a eee oe Okie H-7 

Seed, PATUIOULE  BIZer a ig oS eee a energie tah ie waul ede ee Le eh cae H-8 

H.3.2.3 Attribute Buffer Address... 2... 000000000000. cece eee eee. H-9 

H.3.3 Size and Extend Control .. 2... 0.0.00. 0c ec ee eee eee H-9 

H.3.4 | Window Size and Access Control... ....0..00.00 00000 cece ee eeee H-10 

H.3.5 Filename Block Pointer .........0..0 000.000 cece eee ce eee eeee H-11 

Ha. Placement Control! iy1.4 green,» Vedder ate eat Wel et Sods 68 heh oko sk o e H-11 
Elo” 2Block. Locking -1° seo: Bind Oe Gate a ON ee wea ed & 6 kg cate aoe e H-12 
H.6 Summary of FIIACP Functions... 1.2.2... .0.000 000000 cee eee eee H-12 
H.7 Summary of MTAACP Functions .........0.0 00000000 cece cece eee eee H-14 


Appendix | Field Size Symbols 
ee et 


Ld System: Library Symbols: 5.4 %2 we se Stays Gs Anda pee & aden BoA Wee be a bk I-1 


Appendix J Sample Programs 
Se a at ee 


fel, - RrogranisCR CORY fe uh toi ie Galt acum, ine ute oh lon pte wae inlet a teatie’s J-1 
J.2 PrOptaM-CREOPA NES afaie eh AS AOR ghd Uae dow dos We ok Sek Poe lena ede Boe Wr dboh s J-2 
Jo. ‘ErogramcCRCOPB * i. act ud Got ocean toe ahd Gila oe ak dod we GO WE ite ee Ques eg eS J-3 


Appendix K_ Error Codes 
a es 


Appendix L RSX-11M-PLUS and Micro/RSX FCS Library Options 
se ee ee 


Tet Me Se Dranyy OpHOns: t's a0 sity Aah erst dcace acqta aaa be lawhe yy Bee 2 we ay bara’ L-1 
be? LACIE 2 taeda tan) b Wee ge RAs ee eee oe Ju eh einthan maker Wicleigastends Send L-1 
Index 
eee 
Figures 
SSeS 
T=l! «File Acess ‘Operations ia cea ka Paced ROARS kwe bo Da Rae ele 1-2 
1-2 Sequenced Variable-Length Record ... 0.0.0.0... 0.0000 c eve e enue. 1-7 
1-3. Nonsequenced Variable-Length Record .......... 0.000000 cee eeeeeee 1-7 
1-4 Record I/O Operations ... 2.2... 0. ee eee. 1-10 
1-5 Single Buffering Versus Multibuffering .....................0.00.. 1-11 
aA, (Delault UIC Format, x2 25% a eh ek & BMG avntihy wien Oey Bs a he a Salk 4-4 
4-2 File Protection Word Format. .........0 0.000000 cece c cece eeeee 4-5 


xi 


File Protection Access BitS . 2... 0. ee ee 4-5 


File Owner Word Format... 2.00.6 es 4-6 
Directory Structure for Single-User Volumes .. 1.6.2... 00 etree eres 5-3 
Directory Structure for Multiuser Volumes... 6... ee ee es 5-3 
File Header Block. 0 0... ee 5-4 
Data Flow During Command Line Processing... ...-- +--+ e+e e rere eee 6-2 
Format of Switch Descriptor Table Entry... 1... 21s ee eee ees 6-26 
Format of Switch Value Descriptor Table Entry... .. 2-2... eee eee eee 6-29 
Processing Steps Required to Generate a Parser Program Using TPARS ...... 7-13 
Flow of Control When TPARS Is Called from an Executing User Program .... 7-14 
File Descriptor Block Format... 6.6... et eet es A-2 
Filename Block Format . 0... ee B-2 
ANSI Filename Block Format .. 0.00. 0c ee ee B-4 
Retrieval Pointer Format ... 2... ee C-5 
Statistics Block Format . 0... ee ee D-1 
ANSI Magnetic Tape File Header Block (FCS Compatible)... ........---- G-10 
File Identification Block . 0... eee H-6 
Shared File AcceSS 6. ee 1-14 
FCSRES Routines 2... 1-21 
Macro Calls Generating FDB Information ..... 2... ee eee ees 2-2 
File-Processing Macro Calis... 1... ee es 3-1 
File Access Privileges Resulting from OPEN$x Macro ......--- 02ers 3-4 
R2 Control Bits for EXTND Routine 2... 2... ee ee 4-25 
GCML Offsets and Bit Values 2... ee 6-6 
CSI$ Offsets and Bit Values 2... ee 6-14 
FDB Offset Definitions ©. 6... 0. es A-4 
Filename Block Offset Definitions ©... 6... e ee ee B-3 
Filename Block Status Word (N.STAT) 2.0.2... eee ee B-3 
Filename Block Offset Definitions for ANSI Magnetic Tape ....---- +--+: B-5 
File Header Block Format .. 2.2.0. eee ee es C-1 
File Header Block Contents . 2... 0 ee C-3 
File Header Indentification Area Contents ... 6.6.0... 2 eee eee eee C-4 
Index File Structure 6... E-1 
Home Block Format . 0... 0 ee E-2 
Predefined File Header Blocks «1.1... eee ee E-4 
Summary of I/O-Related System Directives ©... -- ee eee ee tee F-1 
Volume Label Format... 0... ee G-1 
File Header Label (HDR1) .. 2.6... ee G-4 
File Header Label (HDR2) .. 1... ee G-5 
File Header Label (HDR3) .. 1... G-6 


xii 


Pes SUCHE oho oS ue ancy Gs PMG ot Bae eee at ghivend ge LY © gewoon ee Lee quae G-9 


File. Processor Error Codes: 2 4. ..0 4 a Wawe $5.4 D4 a dw aoe Bb a oa ew H-3 
Maximum Size for Each File Attribute ..........................., H-8 
Field Size symbols? ii ie Soa nae oe hak Gre, hae hg eee oie anne tc degag awe ala & I-1 
FCS Library Descriptions... 0... 2.0.0. eee ee. L-1 
HOT POW alles. nnd ett 5 a Pater ds ant ading cabin alee Aeris dette ate oc L-2 


xiii 


Preface 


Manual Objectives 


The purpose of this manual is to familiarize the users of the RSX-11M-PLUS and Micro/RSX 
operating systems with the File Control Services (FCS) facility provided with the system. 


intended Audience 


Because the File Control Services described in this manual pertain to both MACRO-11 and 
FORTRAN programs, the reader is assumed to be familiar with these languages. Also, because 
the development of programs in an RSX-11M-PLUS and Micro/RSX environment requires 
the use of the Task Builder (TKB), the reader should be familiar with the contents of the 
RSX-11M-PLUS and Micro/RSX Task Builder Manual. 


Structure of This Document 


Chapter 1 describes the FCS features available for RSX-11M-PLUS and Micro/RSX users. It 
also defines some of the terminology used throughout the manual. This-chapter is important to 
understanding the balance of the manual. 


Chapter 2 describes the actions you must take at assembly time to prepare adequately for 
all intended file I/O processing through FCS. This chapter describes the data structures and 
working storage areas that you must define within a particular program to use any of the 
File Control Services. Until you are thoroughly familiar with this chapter, you are advised to 
postpone reading subsequent chapters. 


Chapter 3 describes the run-time macro calls that allow you to manipulate files and to perform 
I/O operations. 


Chapter 4 describes a set of run-time routines that perform I/O functions on files, such as 
reading and writing directory entries and renaming or extending files. 


Chapter 5 describes the structure of files for disk, DECtapes, and magnetic tapes supported by 
the RSX-11M-PLUS and Micro/RSX operating systems. 


XU 


Chapter 6 describes two collections of object library routines. The Get Command Line (GCML) 
routine and the Command String Interpreter (CSI) routine may be linked with the user task to 
perform operations that request command line input. Such input consists of file specifications 
that identify and control the files to be processed by your program. 


Chapter 7 describes the table-driven parser (TPARS), which provides you with the means to 
define and parse command lines in a unique user-designed syntax. 


Chapter 8 describes queuing files for printing. You can queue files for printing at both the 
MACRO and subroutine levels. 


Appendix A outlines the File Descriptor Block (FDB). 

Appendix B outlines the filename block (FNB). 

Appendix C describes the format and content of the file header block. 
Appendix D describes the format and content of the statistics block. 
Appendix E illustrates the structure of the index file of a Files—11 volume. 


Appendix F summarizes a number of I/O-related system directives that form a part of the total 
resource management capabilities of the RSX-11M-PLUS Executive. 


Appendix G describes the format and content of the magnetic tape labels. 
Appendix H describes the QIO$ level interface to the file Ancillary Control Processors (ACPs). 


Appendix I lists RSX-11M-PLUS FCS library system generation options and provides a brief 
description of each. 


Appendix J illustrates the use of the macro calls that create and initialize the FDB. The appendix 
presents sample programs that include some of the macro calls used for processing files. 


Appendix K lists the error codes returned by the system. 


Appendix L lists the field-size symbols. 


Associated Documents 


The following manuals provide additional information and may be useful for understanding 
I/O operation logic: 


e RSX-11M-PLUS Information Directory and Master Index 

¢ RSX-11M-PLUS and Micro/RSX Executive Reference Manual 
¢ RSX-11M-PLUS and Micro/RSX Task Builder Manual 

* PDP-11 MACRO-11 Language Reference Manual 


In addition, documentation for programming in any of the PDP-11 languages may be helpful. 
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Conventions Used in This Document 


The following conventions are observed in this manual: 


Convention 


Meaning 


> 


MCR> 
DCL> 
UPPERCASE 


command ab- 
breviations 


lowercase 


/keyword, 
/qualiifier, 
or 

/switch 


parameter 


[option] 


A right angle bracket is the default prompt for the Monitor Console Routine 
(MCR), which is one of the command interfaces used on RSX-11M-—PLUS and 
Micro/RSX systems. 


A dollar sign followed by a space is the default prompt of the DIGITAL 
Command Language (DCL), which is one of the command interfaces used on 
RSX-11M-PLUS and Micro/RSX systems. Many systems include DCL. 


This is the explicit prompt of the Monitor Console Routine (MCR). 
This is the explicit prompt of the DIGITAL Command Language (DCL). 


Uppercase letters in a command line indicate letters that must be entered as 
they are shown. For example, utility switches must always be entered as they 
are shown in format specifications. 


Where short forms of commands are allowed, the shortest form acceptable is 
represented by uppercase letters. The following example shows the minimum 
abbreviation allowed for the DCL command DIRECTORY: 


$ DIR 


Any command in lowercase must be substituted for. Usually the lowercase word 
identifies the kind of substitution expected, such as a filespec, which indicates 
that you should fill in a file specification. For example: 


filename filetype; version 


This command indicates the values that comprise a file specification; values are 
substituted for each of these variables as appropriate. 


A command element preceded by a slash (/) is an MCR keyword; a DCL 
qualifier; or a task, utility, or program switch. 


Keywords, qualifiers, and switches alter the action of the command they follow. 


Required command fields are generally called parameters. The most common 
parameters are file specifications. 


Square brackets indicate optional entries in a command line or a file specification. 
If the brackets include syntactical elements, such as periods (.) or slashes (/), 
those elements are required for the field. If the field appears in lowercase, you 
are to substitute a valid command element if you include the field. Note that 
when an option is entered, the brackets are not included in the command line. 


Square brackets around a comma and an ellipsis mark indicate that you can use 
a series of optional elements separated by commas. For example, (argument 
[, ..- ]) means that you can specify a series of optional arguments by enclosing 
the arguments in parentheses and by separating them with commas. 
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Convention 


{} 


‘argument 


[g-m] 
[directory] 


filespec 


Meaning 


Braces indicate a choice of required options. You are to choose from one of the 
options listed. 


Some parameters and qualifiers can be altered by the inclusion of arguments 
preceded by a colon. An argument can be either numerical (COPIES:3) or 
alphabetical (NAME:QIX). In DCL, the equal sign (=) can be substituted for the 
colon to introduce arguments. COPIES=3 and COPIES:3 are the same. 


Parentheses are used to enclose more than one argument in a command line. 
For example: 


SET PROT = (S:RWED,O:RWED) 


Commas are used as separators for command line parameters and to indicate 
positional entries on a command line. Positional entries are those elements that 
must be in a certain place in the command line. Although you might omit 
elements that come before the desired element, the commas that separate them 
must still be included. 


The convention [g,m] signifies a User Identification Code (UIC). The g is a group 
number and the m is a member number. The UIC identifies a user and is used 
mainly for controlling access to files and privileged system functions. 


This may also signify a User File Directory (UFD), commonly cailed a directory. 
A directory is the location of files. 


Other notations for directories are: [ggg,mmm], [gggmmm], [ufd], [mame], and 
[directory]. 


The convention [directory] signifies a directory. Most directories have 1- to 
9-character names, but some are in the same [g,m] form as the UIC. 


Where a UIC, UFD, or directory is required, only one set of brackets is shown 
(for example, [g,m]). Where the UIC, UFD, or directory is optional, two sets of 
brackets are shown (for example, [[g,m]]). 


A full file specification includes device, directory, file name, file type, and version 
number, as shown in the following example: 


DL2: [46,63] INDIRECT . TXT; 3 


Full file specifications are rarely needed. If you do not provide a version number, 
the highest numbered version is used. If you do not provide a directory, the 
default directory is used. Some system functions default to particular file types. 
Many commands accept a wildcard character (*) in place of the file name, file 
type, or version number. Some commands accept a filespec with a DECnet 
node name. 


A period in a file specification separates the file name and file type. When the 
file type is not specified, the period may be omitted from the file specification. 


A semicolon in a file specification separates the file type from the file version. 
If the version is not specified, the semicolon may be omitted from the file 
specification. 
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Convention 


@ 


KEYNAME 


J 


XXX 


Meaning 


The at sign invokes an indirect command file. The at sign immediately precedes 
the file specification for the indirect command file, as follows: 


Qfilename[.filetype; version] 


A horizontal ellipsis indicates the following: 

¢ Additional, optional arguments in a statement have been omitted. 

¢ The preceding item or items can be repeated one or more times. 

¢ Additional parameters, values, or other information can be entered. 

A vertical ellipsis shows where elements of command input or statements in an 


example or figure have been omitted because they are irrelevant to the point 
being discussed. 


This typeface denotes one of the keys on the terminal keyboard, for example, 
the RETURN key. 


The symbol [CiRl/a] means that you are to press the key marked CTRL while 
pressing another key. Thus, indicates that you are to press the CTRL key 
and the Z key together in this fashion. is echoed on some terminals as 
“Z. However, not all control characters echo. 


A lowercase n indicates a variable for a number. 


A symbol with a 1- to 3-character abbreviation, such as [x] or , indicates that 
ou press a key on the terminal. For example, indicates the RETURN key, 
indicates the LINE FEED key, and indicates the DELETE key. 


In addition, unless otherwise noted, the term “RSX~11” refers to both the RSX-11M-PLUS and 
Micro/RSX operating systems. 
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summary of Technical Changes 


The following sections list features that are new to I/O operations and File Control Services 
(FCS) for the RSX-11M-PLUS and Micro/RSX Version 4.0 operating systems. These new or 
modified features are documented in this revision of the RSX-11M-PLUS and Micro/RSX I/O 
Operations Reference Manual. 


Also, major changes to the organization of the manual are included at the end of this summary. 


New Hardware Support 
RSX-11M-PLUS and Micro/RSX Version 4.0 support the following new hardware: 
e The LOPO3 letter-quality printer 
¢ The LA75 dot matrix printer and LCGO1 graphics printer 
e¢ The DHU11 and DHQ11 asynchronous multiplexers 
¢ The CXA16, CXB16, and CXY08 BA200-series multiplexers 
© The RA82, RD32, and RD54 Winchester disk drives 
¢ The RX33 single flexible disk 


New Features 
No new features have been included for I/O operations in this version of the RSX-11M-PLUS 
and Micro/RSX software. 
Changes to the Document 


The following changes in organization are included in this revision of the RSX-11M-PLUS and 
Micro/RSX I/O Operations Reference Manual. 


e¢ A new appendix has been added to this manual. Appendix H has been included to 
provide system programmers and users with additional information about Ancillary Control 
Processors (ACPs) and their functions. This appendix was formerly included in the 
RSX-11M-PLUS I/O Drivers Reference Manual. 


e The appendixes have been reorganized to provide a more consistent, logical order to the 
manual. 


xxi 


Chapter 1] 
File Control Services 


This chapter describes the File Control Services (FCS) features available for RSX-11M-PLUS 
and Micro/RSX users. It defines some of the terminology used throughout the manual. FCS 
enables you to perform record-oriented and block-oriented I/O operations, as well as additional 
operations required for file control. Open, close, wait, and delete are some of these additional 
operations. The term FCS, as used in this manual, is a substitute for FCSRES, a memory-resident 
library. This memory-resident library contains commonly used routines that are linked with 
your task at task-build time. These routines may also be linked with your task from a system 
object module library (SYSLIB.OLB). There are three kinds of FCS as follows: 


Library Description 


ANSI Supports American National Standards Institute (ANSI) format magnetic tape 
and big buffers. 


Non-ANSI Does not support ANSI tape or big buffers. 
Multibuffered Supports ANSI tape, big buffers, and multiple buffers. 


When your task uses functions such as OPEN$, which opens a file, and CLOSE$, which closes a 
file, the Task Builder (TKB) resolves the address of these routines in FCSRES, thereby eliminating 
these routines from your task image. As a result, FCS routines do not significantly increase 
the size of your task image. If you do not link your task with FCSRES at task-build time, the 
routines must come from SYSLIB and are included in your task image, which increases its size. 
These routines, consisting of pure, position-independent code, provide an interface to the file 
system, enabling you to read and write files on file-structured devices and to process files by 
using logical records. 


Your program regards logical records as data units that are structured in accordance with 
application requirements, rather than as physical blocks of data on a particular storage medium. 
To meet the application’s requirements, FCS allows a collection of data—distinct logical records— 
to be written to a file in a way that enables you to retrieve the data from the file without having 
to know the exact format in which it was written to the file. FCS, therefore, is transparent 
to your task; records can be read or written in logical units that are consistent with particular 
application requirements. 
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To invoke FCS functions from your task or application, your task issues macro calls to specify 
desired file control operations. The FCS macros are called at assembly time to generate code 
for specified functions and operations. The macro calls provide the system-level, file control 
primitives with the necessary parameters to perform the file access operations that you request 
(see Figure 1-1). 


Figure 1-1: File Acess Operation 


User-Issued Macro Call 
File Control Services 
File Control Primitives 


Peripheral Device Hardware 
(For Example, Disk, VT220) 
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1.1 Key Terms Used Throughout This Manual 


Following are terms used throughout this manual; they have unique definitions in the context 
of FCS operations. 


File Descriptor Block 


The File Descriptor Block (FDB) is the data structure that provides FCS with information needed 
to perform I/O operations on a file. The space for this data structure is allocated in your program 
by issuing the FDBDF$ macro call (see Chapter 2). Each file to be opened simultaneously by 
your program must have an associated FDB. Portions of the FDB, which may be defined by you 
or the system, are maintained by FCS. Assembly-time or run-time macro calls are provided for 
you to initialize the FDB. The format and content of the FDB are detailed in Appendix A. 


Filename Block 


The filename block is the portion of the FDB that contains the various elements of a file 
specification (see the File Specification entry in this section) that FCS uses. Initially, as a file is 
opened, FCS fills in the filename block with information that you specify and that is taken from 
the data-set descriptor or the default filename block (see the following subsections). Chapter 2 
describes how FCS fills in the filename block from a file specification; the format and content 
of the filename block are described in Appendix B. 
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Default Filename Block 


The default filename block is an area you allocate within your program by issuing the NMBLK$ 
macro call (see Chapter 2) that contains the various elements of a file specification. You create 
the default filename block; whereas, the filename block within the FDB is maintained by FCS. 
You create the default filename block to supply file specifications to FCS that are not otherwise 
available through the data-set descriptor (see the next entry). FCS takes these file specifications 
and creates a parallel structure in the FDB that contains information that FCS requires during 
execution time in opening and operating on files. 


Thus, the terms “default filename block” and “filename block” refer to separate and distinct 
data structures. These distinctions should be kept in mind whenever these terms appear in this 
manual. These areas are structurally identical, but they are created and used differently, and 
they may contain different information at different times. 


Data-Set Descriptor 


The data-set descriptor is a 6-word block in your program that contains the sizes and the 
addresses of American Standard Code for Information Interchange (ASCII) data strings that 
together constitute a file specification (see Section 1.9). This 6-word block, which you also 
create, is described in detail in Chapter 2. Unless the filename block in the FDB has been 
initialized, you must provide FCS with data-set descriptor or default filename block information 
before the specified file can be opened. 


Data-Set Descriptor Pointer 


The data-set descriptor pointer is an address value that points tothe 6-word data-set descriptor 
within your program. This address value is stored in the FDB, allowing FCS to access a file 
specification that you created in the data-set descriptor. 


File Specification 


The file specification is the unique file identification that names a file, specifies the location, 
and allows the location to be explicitly referenced by any task. The operating system, or your 
task, must refer to files by using a file specification. The file specification contains specific 
information that must be made available to FCS before that file can be opened. See Section 1.9 
for a description of a file specification. 


File Storage Region 


The file storage region (FSR) is an area of memory that you reserve for use in I/O operations 
(see Section 1.7.3). You can allocate this area by issuing the FSRSZ$ macro call in your program 
(see Chapter 2). 
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1.2 Important FCS Characteristics 
You should be aware of the following FCS characteristics when using I/O facilities: 


* I/O operations initiated by READ$ and WRITE$ macros are asynchronous; you are 
responsible for coordinating all block I/O activity. 


¢ I/O operations initiated by GET$ and PUT$ macros are synchronized entirely by FCS; 
control is not returned to your program until the requested GET$ or PUT$ operation is 
complete. 


* FCS macro calls save and restore all registers, with the following exceptions: 


— The file-processing macro calls (see Chapter 3) and the run-time FDB initialization 
macros (see Chapter 2) place the File Descriptor Block (FDB) address in RO. 


- Many of the file control routines (see Chapter 4) return requested information in the 
general registers. 


° The macro that defines and allocates the space for the FDB is the FDBDF$ macro (see 
Chapter 2). Once the FDB is allocated, necessary information can be placed in this data 
construct through any logical combination of assembly-time or run-time macro calls (see 
Chapter 2). Certain information must be present in the FDB before FCS can open and 
operate on a specified file. 


e For each assembly-time FDB initialization macro call, a corresponding run-time macro call 
is provided that supplies identical information. Although both sets of macro calls (see 
Chapter 2, Table 2-1) place the same information in the FDB, each set does so in a different 
way. The assembly-time calls generate .BYTE or .WORD directives that create specific data, 
while the run-time calls generate MOV or MOVB instructions that place desired information 
in the FDB during program execution. 


° [If an error condition is detected during any of the file-processing operations described in 
Chapter 3, or during the execution of several of the file control routines (see Chapter 4), 
the Carry bit in the Processor Status Word (PSW) is set, and an error indicator is returned 
to FDB offset location F.ERR. 


Note 
When you use the READ$ or WRITE$ macros to execute system I/O, the 1/O 
status block (IOSB) parameter must be specified for F.ERR and the Carry bit to 
be properly returned (see Chapter 3). 


If the address of a user-defined error-handling routine is specified as a parameter in any of the 
file-processing macro calls, a jump to subroutine program counter (JSR PC) instruction to that 
error-handling routine is generated. The routine is then executed if the Carry bit in the PSW is 
set. 
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1.3 FCS Data Structures 


In addition to generating calls to FCS subroutines, FCS macros issued by your task create and 
maintain certain data structures that file 1/O operations require. These required data structures 
include the following: 


e A File Descriptor Block (FDB) that contains information necessary for processing the file. 


° A data-set descriptor that FCS accesses to obtain ASCII file name information required to 
open a specified file. 


¢ A default filename block that FCS accesses to obtain default file name information to open 
a specified file. FCS accesses the default filename block when complete file information is 
not specified in the data-set descriptor. 


e A file storage region (FSR) that FCS uses for working storage. The FSR is described in 
Section 1.3.3. 


1.3.1 File Descriptor Block 


The File Descriptor Block (FDB) contains information that FCS uses to open and process files. 
One FDB is required for each file that your program opens simultaneously. You initialize some 
portions of the FDB with assembly-time or run-time macro calls, and FCS maintains other 
portions. Each FDB has the following five sections that contain information that your task or 
the system defines: 


e File attribute section 

e Record or block access section 
e File open section 

e Block buffer section 

e Filename block portion 


The information stored in the FDB depends upon the characteristics of the file to be processed. 
The FDB and the macro calls that cause values to be stored in this structure are described in 
detail in Chapter 2. Appendix A describes the format and the content of the FDB. 


1.3.2 Data-Set Descriptor and Default Filename Block 


You must specify either a data-set descriptor or a default filename block for each file that you 
intend to open. These data structures provide FCS with the file specifications required for 
opening a file. Although either the data-set descriptor or the default filename block is usually 
specified, you may also specify both for the same file. The data-set descriptor and the default 
filename block are further described in detail in Chapter 2. 


When a file is being opened using information already present in the filename block, neither 
the data-set descriptor nor the default filename block is accessed by FCS for required file 
information. This method of file access, which is termed “opening a file by file ID,” is an 
efficient means of opening files. Chapter 2 describes this process in detail. 
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1.3.3 File Storage Region 


The file storage region (FSR) is an area allocated in your program as working storage for record 
I/O operations (see Section 1.7). The FSR consists of four program sections that are always 
contiguous. These program sections exist for the following purposes: 


$$FSR1 This area of the FSR contains the block buffers and the block buffer headers for 
record I/O processing. You determine the size of this area at assembly time by 
issuing the FSRSZ$ macro call (see Chapter 2). The number of block buffers 
and associated headers is based on the number of files that you intend to open 
simultaneously for record I/O operations. 


$$FSR2 This area of the FSR contains impure data that FCS uses and maintains when 
performing both record and block I/O operations. Portions of this area are initialized 
at task-build time, and other portions are maintained by FCS. 


The size of the FSR can be changed, if desired, at task-build time. Chapter 2 shows you how 
to do this. 


1.4 File Access Methods 


RSX-11M-PLUS and Micro/RSX systems support both sequential and random access to data 
in files. Sequential access devices include magnetic tapes and card readers. Random access 
devices include disks. The sequential access method is device independent; that is, sequential 
access is usable on both record-oriented and random access devices (for example, card readers 
and disks). You can use the random access method only for random access devices. 


1.5 Data Formats for File-Structured Devices 


Data is transferred between peripheral devices and memory in blocks. A data file consists of 
virtual blocks, each of which may contain one or more logical records created by your program. 
In FCS terms, a virtual block in a file consists of 512;9 bytes for random access devices. The 
size of the logical records in the virtual blocks is under the control of the program that originally 
wrote the records. 


When creating a new file, your program can specify that the records in the file will differ in 
size. Such records are known as variable-length records. Conversely, if your program indicates 
that all records in the new file will be equal in size, the records are known as fixed length. 


There are two types of variable-length records: sequenced and nonsequenced. Both must be 
word aligned; that is, each record must be stored as an even number of bytes. Sequenced 
variable-length records are preceded by a 2-word record header. The first word contains the 
length of the record (in bytes), and the second word contains the value of the sequence number 
as shown in Figure 1-2. The record length information is used to determine the end of each 
record and the beginning of its successor. Note that the word containing the sequence number 
is included in the record length. 
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Figure 1-2: Sequenced Variable-Length Record 
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Nonsequenced variable-length records are preceded by a single-word record header containing 


the length of the record as shown in Figure 1-3. 


Figure 1-3: Nonsequenced Variable-Length Record 
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Both fixed- and variable-length records are aligned on a word boundary. Any extra byte that 
results from an odd-length record is simply ignored. It is not included in the record length. 


(The extra byte is not necessarily a 0 byte.) 


Virtual blocks and logical records within a file are numbered sequentially, each starting at 1. A 
virtual block number is a file-relative value; whereas, a logical block number is a volume-relative 
value. Ordinarily, records may cross block boundaries. Crossing block boundaries means that 


the beginning of a record can fill out the end of a block, while the rest of the recor 


the beginning of the next block. 
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1.5.1 Data Formats for ANSI Magnetic Tape 


You can use both fixed- and variable-length records on magnetic tape; their format conforms to 
the ANSI standard. 


On magnetic tape, a virtual block corresponds to a physical record. The default length of a 
block is 512 bytes. Its length can be changed to any value from 8 to 819219 bytes (14 to 
819219 bytes for a write function) with the use of the FDBF$ macro (see Chapter 2). Records 
are not allowed to cross block boundaries. 


Fixed-length records are packed into a block with no control information and no padding for 
alignment. The block is truncated so that it ends at the word boundary immediately following 
the last record that will fit in the block buffer. 


Variable-length records are preceded by a 4-byte count field, which is expressed in decimal in 
ASCII characters. The count includes the length of the record and the 4-byte count field. After 
the last record in a block (if there is any space left in the block), a caret character (, ASCII 
code 136) appears where the next byte count should be, signaling the end of data in that block. 


1.6 Block I/O Operations 


Block I/O operations provide an efficient means of processing file data because such operations 
do not involve the blocking and deblocking of records within the file. Also, block I/O operations 
permit your task to read or write files in an asynchronous manner; that is, control may be 
returned to your program before the requested 1/O operation is completed. 


The read and write macro calls (READ$ and WRITE$) allow your task to read and write 
virtual blocks of data to and from a file without regard to logical records within the file. (See 
Chapter 3 for a description of READ$ and WRITE$ macro calls.) When your task uses block I/O, 
the number of the virtual block to be processed is specified as a parameter in the appropriate 
READ$ or WRITE$ macro call. The virtual blocks so specified are processed directly in a 
reserved buffer in your task’s memory space. Your task can use READ$ and WRITES only on 
block-structured devices. 


You are responsible for synchronizing all block I/O operations. Such asynchronous operations 
can be coordinated through an event flag (see Chapter 2) specified in the READ$/WRITE$ 
macro call, The system uses the event flag to signal the completion of a specified block I/O 
transfer, enabling you to coordinate those block I/O operations that are dependent on each 
other. 


1.7 Record 1/O Operations 


Sequential access mode I/O operations can be performed for both fixed- and variable-length 
records. Random access mode I/O operations can be performed only for fixed-length records. 
Your program accesses records randomly by specifying a record number. This number represents 
the position of the desired record within the file (viewing the file as an array of fixed-sized 
records, with the number 1 representing the first record physically present in the file and n the 
last). 
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The GET$ and PUT$ macro calls (see Chapter 3) are provided for processing individual records 
in files. Using the FSR block buffers (see Section 1.3.3), the GET$ and PUT$ routines perform 
the necessary blocking and deblocking of records within the virtual blocks of the file, allowing 
your program to access logical records. Successive GET$ or PUT$ operations in random access 
mode can access records anywhere within the file. To do so, your program need only modify 
the record number specified as part of the random record operation. After each such random 
operation, FCS increases by 1 the record number used in the operation. If your program does 
not again modify this number prior to issuing another record operation, the record actually 
accessed is the next sequential record in the file. 


In contrast to block I/O operations, all record I/O operations are synchronous; that is, control 
is returned to your program only after the requested I /O operation is completed. 


Because GET$ or PUT$ operations process logical records within a virtual block, only a limited 
number of GET$ or PUT$ operations result in an actual I/O transfer (for example, when the 
end of a data block is reached). Therefore, all GET$ or PUT$ I/O requests do not necessarily 
involve an actual physical transfer of data. 


The data flow during record I/O operations is shown in Figure 1-4, Note that blocks of data 
are transferred directly between the FSR block buffer and the device containing the desired file. 
The deblocking of records during input occurs in the FSR block buffer, and the blocking of 
records occurs in the FSR block buffer during output. Note also that FCS serves as your task’s 
interface to the FSR block buffer pool. All record I/O operations, which are initiated through 
GET$ and PUT$ macro calls, are synchronized by FCS. 
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Figure 1-4: Record I/O Operations 
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1.7.1 Record I/O Data-Transfer Modes 


By using record I/O, a program can gain access to a record in either of the following two ways 
after the virtual block has been transferred into the FSR from a file: 


* In move mode, by specifying that individual records are to be moved from the FSR block 
buffer to a record buffer that you have defined (see Figure 1-4) 


e In locate mode, by referencing a location in the File Descriptor Block (see Section 1.3.1) that 
contains a pointer to the desired record within the FSR block buffer 


Move Mode 


Move mode requires that data be moved between the FSR block buffer and a record buffer 
that you have defined. For input, data is first read into the FSR block buffer from a peripheral 
device and then moved to your task’s record buffer for processing. For output, your program 
builds a record in your task’s record buffer; FCS then moves the record to the FSR block buffer, 
from which it is written to a peripheral device when the entire block is filled. 


Move mode simulates the reading of a record directly into your task’s record buffer; thus, the 
blocking and deblocking of records is transparent. 
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Locate Mode 


Locate mode enables your task to access records directly in the FSR block buffer. Consequently, 
there is normally no need to transfer data from the FSR block buffer to your task’s record buffer. 
To access records directly in the FSR block buffer, refer to locations in the File Descriptor Block 
(see Section 1.3.1 and Appendix A) that contain values defining the length and the address of 
the desired record within the FSR block buffer. These values are present in the FDB as a result 
of FCS macro calls that you issued. 


Program overhead is reduced in locate mode because records can be processed directly within 
the FSR block buffer. Moving data to your task’s record buffer in locate mode is required only 
when the last record of a virtual block crosses block boundaries. 


1.7.2 Multibuffering for Record |/O 


By supporting multiple buffers for record I/O, FCS provides the ability in multibuffered FCS to 
tread data into buffers in anticipation of user program requirements and to write the contents 
of buffers while your program is building records for output. (Multibuffered FCS is a SYSGEN 
option.) You can thus overlap the internal processing of data with file I/O operations, as 
illustrated in Figure 1-5. 


When your task uses read-ahead multibuffering, the file must be sequentially accessed to derive 
full benefit from multibuffering. For write-behind multibuffering, you can use any file access 
method with full benefit. 


When your task uses multibuffering, you must allocate sufficient space in the FSR for the total 
number of block buffers in use at any given time. The FSRSZ$ macro call (see Chapter 2) 
allocates space for FSR block buffers. 


Figure 1-5: Single Buffering Versus Muitibuffering 
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1.7.2.1 Multibuffering Performance 


Multibuffering can improve performance for 1/O-bound tasks under certain circumstances. 
However, multibuffer processing in random mode is not very efficient. Multibuffering in 
random mode always requires a user record buffer. If one is not supplied, the task’s low 
memory may be overwritten and the task may abort. 


For example, consider an I/O-bound task running as the dedicated or highest priority application 
on a system. For such a task, multibuffering can decrease overall processing time by enabling 
overlap of I/O and task execution. 


However, if other tasks run at the same priority as that of the application task described 
previously, then an overlap of 1/O and task execution is already achieved among these tasks 
without multibuffering. In this case, multibuffering would use up address space and pool 
without improving execution speed. If virtual and physical address space is available, big 
buffering would improve performance (see Section 1.7.3). However, big buffer processing in 
random mode is not very efficient. 


1.7.3 Big Buffering for Record /O 


If the task uses large records or operates on clusters of records, big buffering is advantageous. 
The use of big buffering assumes that it is reasonable to use more task address space and 
physical memory for increased buffer space, and it is reasonable to use more pool for the 
increased number of outstanding I/O packets. 


Big buffering reduces the number of disk accesses by allowing multiblock input and output. 
Normally, the disk accesses for GET$ or PUT$ operations are performed one sector at a time. 
Using FCS big buffers allows you to read or write a specified number of sectors in a single 
operation. 


When using big buffering in random mode, a user task record buffer is always required. If one 
is not supplied, the task’s low memory may be overwritten and the task may abort. Using big 
buffering with random GET$ and PUT$ can cause data to be lost from the end of a file. In this 
case, a directory of the file would indicate more blocks in use than it had allocated. To prevent 
this condition from happening, follow these steps: 


1. Preallocate enough space to make writing an extension unnecessary. 
2. Execute a FLUSH operation after the highest-numbered record is written by a PUT$ macro. 


3. After a PUT$ macro, arrange not to execute any GET$ macro that could cause the file to 
extend. 


To use big buffers, you must select the buffer size and specify that buffer size in the parameter 
lists for each occurrence of both the FSRSZ$ macro and the FDBDF$ macro in your program. 


You should choose a buffer size that is a multiple of 51219 bytes, the size of one disk block. 
Because the default amount allocated by a file extend is five blocks and disks often contain 
many 5-block files or parts of files, a buffer size of five blocks is generally a good choice. Larger 
amounts may increase performance, but note that you are trading large amounts of memory for 
speed. 
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You must reserve the buffer space in your program, and you must specify the buffer size to 
the FDB. The FSRSZ$ macro allows you to specify the total buffer space needed. Specify 
51219 bytes for each normal disk file, plus the buffer size that you have selected for each big 
buffered file. For example, assume that a program has three files: one normal file (512i9-byte 
buffer); one file with a big buffer size of three blocks; and one file with a big buffer size of five 
blocks. The following call to the FSRSZ$ macro reserves the space properly: 


FSRSZ$ 3, <<1+3+5>*512.> 


In the FDB of each file that has a big buffer, you must override the default buffer size by using 
either the FDBF$A macro or the FDBF$R macro. For a file with five blocks as a big buffer, the 
assembly-time macro call is as follows: 


FDBF$A ,<5*512.> 


On RSX-11M-PLUS and Micro/RSX systems, the SYSLIB provided as the default library contains 
all the proper FCS modules for big buffer support. 


1.8 Shared Access to Files 


The Files-11 disk architecture permits shared access to files according to established conventions. 
You can issue one of two macro calls, among several available in FCS for opening files, to 
invoke these conventions. The OPNS$x macro call (see Chapter 3) specifically opens a file 
for shared access. The OPEN$x macro call (see Chapter 3), on the other hand, invokes 
generalized open functions that have shared-access implications only in relation to other I/O 
requests subsequently issued. Both macro calls take an alphabetic suffix that specifies the type 
of operation being requested for the file, as follows: 


R Read existing file. 

Ww Write (create) a new file. 

M Modify existing file without extending its length. 

U Update existing file and extend its length, if necessary. 
A Append data to end of existing file. 


The suffix R applies to the reading of a file; whereas, the suffixes W, M, U, and A all apply to 
the writing of a file. You can use the OPNS$x and OPEN$x macro calls as follows for shared 
access to files: 


1, When the OPNS$R macro call is issued, read access to the file is granted unconditionally, 
regardless of the presence of one or more concurrent write-access requests to the file. (The 
OPNS$R macro call permits concurrent write accesses to the file while it is being read.) 
Subsequent write-access requests for this same file are honored. Thus, several active read- 
access requests and one or more write-access requests may be present for the same file. 
However, multiple tasks simultaneously accessing the file for write operations are subject 
to certain restrictions, as detailed in number 2. 


2. While FCS allows concurrent write-access requests through the use of the OPNS$W, 
OPNS$M, OPNS$U, and OPNS$A macro, synchronizing access to the file is your task’s 
responsibility. To avoid the retrieval or storage of inconsistent data, each task must 
implement and use some mechanism, which you define, ensuring that the file is serially 
accessed. 
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3. When the OPEN$R macro call is issued, read access to the file is granted, provided that 
no write-access requests for that file are active. (The OPEN$R macro call does not permit 
concurrent write access to the file while it is being read.) 


Note from the previous text that readers of a shared file should be aware that the file may yield 
inconsistent data from request to request if that file is also being written. 


Shared access during reading does not necessarily mean that the access requests are all from 
separate tasks. A file could also be shared by a single task that has opened the file on several 
different logical unit numbers (LUNs). 


Table 1-1 shows the circumstances under which Files-11 permits a second file access when the 
file is opened for shared access. 


Table 1-1: Shared File Access 
First Access 
Second Access Read Shared Read Write Shared Write 


Read Yes Yes No No 
Shared Read Yes Yes Yes Yes 
Write No Yes No No 
Shared Write No Yes No Yes 


a 


1.9 File Specification Syntax 
A full file specification has the following elements, in the order listed: 


device 
directory 
name 


type 


version 
A file specification has the following format: 
device: {directory]filename.filetype; version 
An example of a full file specification follows: 


LB: [1,*]SUPLIB.OLB;O is a full file specification. 
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1.9.1 Device 


The device element of the file specification names the device on which the file resides. For 
unit-record devices, such as terminals and line printers, this is the only significant element in 
the file specification. 


Except for logical names, the device specification consists of two alphabetic characters specifying 
the device name, followed by a 0- to 3-character octal numeric string specifying the device unit 
number, followed by a colon (:). FCS converts lowercase alphabetic characters to uppercase 
before passing them to the operating system. The device unit number must not exceed 3773; if 
no unit number is given, FCS assumes unit 0. 


For example: 
db2 and DB02 __Indicate equivalent device specifications. 
SY and sy00 Indicate equivalent device specifications. 


login and LOGIN Indicate equivalent logical device specifications, 


1.9.2 Directory 


The directory element of the file specification names the directory through which the file can 
be found on the device. For ANSI magnetic tape files, this element is not significant (see 
Appendix A). 


If you use numbered directories, the directory specification can take either of the following 
forms: 


(group, member] 
or 
<group ,member> 


Note that the delimiting characters ({] or <> ) and the comma (,) must appear as shown. The 
group and member subelements each consist of a 1- to 3-digit octal number in the range of 0g 
to 377s. In situations where wildcards are permitted, you can substitute a single asterisk (*) 
character for the group or member subelement, or both, to indicate that all such elements are 
acceptable. 


You can explicitly request the current default directory by specifying [] or <> as the directory 
specification. For example, [27,36] and <027,036> are equivalent directory specifications. 


The following list shows the use of various wildcard substitutions: 


ee =, 


Directory 

Specification Meaning 

[27,*] Indicates all members in group 27. 

[*,*] Indicates all User File Directories (UFDs). 

[*] Indicates all UFDs (for named directories only). 

{] Indicates the current default directory (named directories only). 
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If you use named directories, the directory specification can take any of the following forms: 
e [1- to 9-character name] or <symbol> (1- to 9-character name) 

© [001009036] or <symbol> (001009036) 

e —[name09030] or <symbol> (name09030) 


Note that the delimiting characters ([] or <-> ) must appear as shown. The name may consist 
of as many as nine characters. The characters must be only the 36 alphanumeric characters 
from A to Z and 0 to 9. In situations where wildcards are permitted, you can substitute a single 
asterisk (*) character for the named directory. 


1.9.3 Name 


The name element of the file specification is the name by which the file is known in the 
directory. The name specification is a 0- to 9-character alphanumeric string. That is, the 
alphabetic characters A to Z and the numbers 0 to 9 are allowed. FCS converts lowercase 
alphabetic characters to uppercase before passing them to the operating system. 


In situations where wildcards are permitted, you can substitute an asterisk (*) character in the 
name string for any string including the null string. 


For example, the following names are acceptable within a file specification: 


MyFile.; Interpreted as MYFILE.. 


*.; Matches file specifications with null types and versions. 
#5 Interpreted as the null name of 0 length. 
1.9.4 Type 


The type element of the file specification is the type by which the file is known in the directory. 
The type specification consists of a period (.) followed by a 0- to 3-character alphanumeric 
string. FCS converts the lowercase alphabetic characters to uppercase before passing them to 
the operating system. In situations where wildcards are permitted, you can substitute asterisks 
for any string including the null string. 


The following examples show some of the conversions that FCS makes: 


eee ot se ge eS 


FCS 
File Type Interpretation 
.dat Interpreted as .DAT. 
* Interpreted as all types. 


Interpreted as the null type. 


1.9.5 Version 


The version element of the file specification provides the version number by which the file is 
known in the directory. The version specification consists of a semicolon (;) followed by a 
0- to 5-digit octal number in the range of 0 to 77777. 
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Note 


On RSX-11M-PLUS and Micro/RSX systems, decimal numbers are a system 
generation option. Decimal numbers can range from 0 to 32767. 


In situations where wildcards are permitted, you can substitute a single asterisk for the octal 
number to indicate that all versions are acceptable. In situations where you are specifying a file 
that already exists, you can substitute the two characters “-1” for the octal number to specify 
the lowest-numbered version of the file that is known to the directory. 


You can specify a version number of 0 or the null version to indicate either of the following: 


* The highest-numbered version of the file that is known to the directory, when the file 
already exists 


* A version number one greater than the highest-numbered version of the file (if any) known 
to the directory, when you are creating a new directory entry 


The following show some conversions that FCS makes regarding version numbers: 
9 and ;0005 _—sIndicates equivalent versions. 

* Indicates all versions. 

3-1 Indicates the lowest-numbered version. 

7 Indicates the null version; this is equivalent to ;0. 


For compatibility with other systems, FCS access methods can process version specifications 
beginning with a period (.) instead of a semicolon (;) when the presence of a type specification 
eliminates ambiguity. 


1.10 ANSI Magnetic Tape File Specification Syntax 


The file specification format specific to magnetic tapes consists of the following elements, in the 
order listed: 


device 
directory 
quoted string 
version 


1.10.1 Device 


The device element is the same as that described in Section 1.9.1. The device must be a 
magnetic tape device. 


1.10.2 Directory 


The directory element is the same as that described in Section 1.9.2. This element has no 
meaning for ANSI magnetic tape files, and it is ignored if present. 
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1.10.3 Quoted String 


FCS treats a quoted string as a unit representing both the name and type elements of a standard 
file specification. This mechanism allows expression of tape file names up to 17 characters 
in length that include the full set of ANSI “a” characters (some of which would otherwise be 
ignored or treated as element delimiters in a standard file specification). 


You specify an ANSI name by including the name in quotation marks (“name”). If the name 
itself contains full quotation marks (”), you must also precede each such character with an 
additional full quotation character (”). FCS converts any lowercase alphabetic characters to 
uppercase, strips the full-quotation marks that you have added, and passes the result to the 
operating system without further modification (including ANSI “a” characters such as space). 


The following examples show the results of FCS-processed quoted strings: 
“My File” Interpreted as MY FILE. 
“Don’t Panic” Interpreted as “DON’T PANIC.” 


1.10.4 Version 


The version element of a magnetic tape file specification is the same as that for a conventional 
file specification (see Section 1.9.5). A version specification of ;0, ;-1, or the null version is 
interpreted as any version for magnetic tape files. 


1.10.4.1 Example Magnetic Tape File Specification 
An example of an ANSI magnetic tape file specification follows: 
MU1:"KIM's file" specifies any version of KIM'S FILE on device MU1: 


The standard file specification format described in Section 1.9 can also be used with magnetic 
tapes; this permits file transport to nontape devices and file accessibility by the widest possible 
range of software. See Appendix G for additional information concerning the use of names in 
ANSI magnetic tape files. 


1.11 Generation of a Full File Specification 


When you specify the target file for an FCS operation, FCS generates a full file specification in 
the following manner: 


1. FCS parses the filename string to determine which elements are present. You need not 
provide a full file specification in the filename string; however, any elements present must 
be syntactically correct and in the proper order. FCS ignores any null, space, or tab 
characters that may be present in the string unless they occur within an ANSI magnetic 
tape quoted-string name. 


2. FCS processes the default filename block to determine which elements are present. You 
need not provide a full file specification in the default filename block. 
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3. If the filename string does not provide a full file specification, FCS obtains missing elements 
from the default filename block; if any elements are missing after this merge, FCS provides 
default values for them as follows: 


Device Defaults to the device to which the specified logical unit is currently assigned; 
if the specified logical unit is not assigned to any device, defaults to SY. 


Directory Defaults to the current directory. 


Name, type, _ Defaults to null. 
and version 


1.12 Logical Names 
A logical name is a name that you or the system defines for either of the following: 
¢ All or part of a file specification 
¢ A physical device 


Logical names support is a system generation option for RSX-11M-PLUS systems. It is 
automatically included for Micro/RSX systems. 


To keep your program and command procedures independent of physical file specifications, you 
can substitute a logical name for all or part of a file specification, either interactively or from 
within a program or command procedure. 


A logical name may contain 1 to 63 alphanumeric characters, including the special characters 
dollar sign ($) and underscore (_). 


A logical name must have an entry in the logical name table. 


If the first character of the logical name is an underscore (_), the translation process that 
replaces the logical name with its equivalent string removes the underscore only. Thus, the 
input string is not translated, the translation stops, and the resultant string remains. 


A logical name may be a device name or a file name. If a logical name is a device name, it 
must be terminated by a colon (:). 


You can assign logical names to devices such as tape drives, terminals, and line printers. The 
system manager may assign logical names to public disk volumes, so that you do not have to 
be concerned with the physical location of those volumes. 


In addition, to reduce typing, you can use logical names as a shorthand way of specifying files 
or directories that you refer to frequently. For example, you might assign the logical name 
HOME to your task’s default disk and directory. 
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1.12.1 Using Logical Names for Program Input and Output 


Programs that read and write data can be designed to read from or write (perform I/O) to 
different files or devices each time they are run. Performing I/O to different files or devices at 
different times is called device and file independence and is accomplished through the use of 
logical names. 


When you write a program, you can refer to an input or output file by using a logical name. 
For instance, you might use INFILE to represent the data file or input device from which the 
program is to read, and you might use OUTFILE to represent the file or device to which the 
program is to write. After your program is compiled and linked, but before it is run, you use 
system commands to associate the logical names you used in the program with the actual files 
or devices you want to use when you run the program. 


The DEFINE and ASSIGN commands associate the logical names with the files or devices. They 
establish the correspondence between a logical name (that is, the name that you used in the 
program) and an equivalence name (that is, the actual file or device name that you want the 
program to use). 


1.12.1.1 Logical Name Tables 


The system maintains logical name and equivalence name pairs in four logical name tables. 
Following is a description of each table: 


Task logical name table Contains logical name entries that are created for an individual 
task by using the Create Logical (CLOGS) directive. These entries 
remain in the table for only as long as the task is running. When 
either the task has completed execution or the Delete Logical 
(DLOGS$) directive has been issued, the logical names are removed 
from the table. 


User logical name table Contains logical name entries that are local to a particular task. By 
default, the DEFINE and ASSIGN commands place a logical name 
in the user logical name table. 


Group logical name table Contains logical name entries that are qualified by a group number. 
These entries can be accessed only by tasks that execute with the 
same group number in their User Identification Codes (UICs) as 
the task that assigned the logical name. 


System logical name table Contains entries that can be accessed by any task in the system. 


1.12.1.2 Specifying Logical Names 


Logical names and their equivalence name strings can have a maximum of 63 characters, and 
you can use them to form all or part of a file specification. If only part of a file specification is a 
logical name, it must be the leftmost component of the file specification. You can then specify 
the logical name in place of the device name or device and directory name in subsequent file 
specifications. A logical name can contain both a device name and a directory name. 


The equivalence name for a logical name must contain the proper punctuation for a file 
specification (colons, brackets, and periods). If the equivalence name is a device name, it must 
be terminated by a colon (:). 


Logical name translation is discussed in Chapter 4. 
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1.13 Routines Included in FCSRES 


Table 1-2 lists the routines contained in all forms of FCS. However, the routines included in 
the overlaid version FCSRES are placed into two overlay segments. The first overlay segment 
includes routines used for open, close, and associated user-accessible routines. The second 
overlay segment includes routines used for get, put, read, write, and other user-accessible 
routines. 


Table 1-2: FCSRES Routines 


Routine Name Module Name 


First Overlay Segment 


ASCII UIC to Binary Conversion ASCPPN 
Assign Logical Unit Number ASSLUN 
Binary UIC to ASCII Conversion PPNASC 
Close CLOSE 
Delete File DELJMP, DELETE 
Delete File by Filename Block DEL 
Directory Primitives DIRECT 
Extend File EXTEND 
Expand Logical Name and Return -EXPLG 
Pointer to Expanded String 
File Storage Region Initialization FINIT 
Get Directory GETDIR 
Get Directory ID GETDID 
Mark for Deletion (Internal) MKDL 
Mark for Deletion (User Interface) MRKDL 
Octal to Decimal Conversion ODCVT 
Open OPNJMP, OPENR 
Parse PARSE 
Parse Device PARSDV 
Parse Directory PARSDI 
Parse File Name PARSFN 
Print $PRINT 
Rename RENAME 
Request Logical Core Block RQLCB 
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Table 1-2 (Cont.): FCSRES Routines 
Routine Name 

First Overlay Segment 

Send Data to and Start a Subsidiary Task 
Truncate and Close File 


User Directive Primitives 


Second Overlay Segment 
Arithmetic Routines 

ASCII to Binary Conversion 

Binary to ASCII Conversion 

Convert Double Precision to Decimal 
Double Precision Arithmetic Routines 
Edit Message 

Edit Time and Date 

Exit with Status 

Read/Write File Storage Region 2 
Flush 

Get Record 

Obtain Library Attributes 

Octal to Binary Conversion 


Parse Command Line 


Point and Mark 
Position Record 
Put Record 
QIO 

Read Block 
Return Position 


User Device Control Function 
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Module Name 


DSPAT 
TRNCLS 
UDIREC 


ARITH 
CATB 
CBTA 
CODMG 
DARITH 
EDTMG 
EDDAT 
EXST 
RWFSR2 
FLUSH 
GETJMP, GET 
FCSTYP 
.OD2CT 


.CSIL, .CSI2, 
.CS14, .EXPLG 


PNTMRK 
POSREC 
GETJMP, PUT 
XQIOU 

READ 

POSIT 
CONTRL 


Table 1-2 (Cont.): FCSRES Routines 
Routine Name Module Name 


Second Overlay Segment 


Wait WAITU 
Write Block WRITE 
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Chapter 2 
Preparing for 1/O 


This chapter describes the macro calls that your task must invoke to provide the necessary 
file-processing information for the File Descriptor Block (FDB). 


2.1 General Information 


The MACRO-11 programmer must establish the proper database and working storage areas 
within the particular program to perform I/O operations. You must do the following: 


1. Define a File Descriptor Block (FDB) for each file that your program is to open simultaneously 
(see Section 2.2). 


2. Define a data-set descriptor or a default filename block, or both (see Sections 2.5.1 or 2.5.2, 
respectively) if you intend to access these structures to provide file specifications that FCS 
requires. 


3. Establish a file storage region (FSR) within the program (see Section 2.6). (The initialization 
procedures for FORTRAN tasks are described in detail in the PDP-11 MACRO-11 Language 
Reference Manual.) 


Your task can place such information in the FDB in one of three ways: 

* By the assembly-time FDB initialization macro calls (see Section 2.3.1) 
° By the run-time FDB initialization macro calls (see Section 2.3.2) 

e By the file-processing macro calls (see Chapter 3) 


Data supplied during the assembly of the source program establishes the initial values in the 
FDB. Data supplied at run time can either initialize additional portions of the FDB or change 
values established at assembly time. Similarly, the data supplied through the file-processing 
macro calls can either initialize portions of the FDB or change previously initialized values. 
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Table 2-1 lists the macro calls that generate FDB information. 


Table 2-1: Macro Calls Generating FDB Information 


Assembly-Time FDB Run-Time FDB File-Processing 
Macro Calls Macro Calls Macro Calls 
FDBDF$ (required) FDAT$R OPENS$ (all variations) 
FDAT$A FDRC$R CLOSE$ 
FDRC$A FDBK$R GET$ (all variations) 
FDBK$A FDOP$R PUT$ (all variations) 
FDOP$A FDBF$R READ$ 
FDBF$A WRITE$ 

DELET$ 

WAIT$ 


2.2 .MCALL Directive—Listing Names of Required Macro 
Definitions 
You must list as arguments in a .MCALL directive all the assembly-time, run-time, and file- 


processing macro calls (see Table 2-1) that you intend to issue in a program. Doing so allows 
the required macro definitions to be read in from the System Macro Library during assembly. 


You must write the .MCALL directive and associated arguments in the program prior to writing 
any macro call in the execution code of the program. If the list of macro names is lengthy 
in the .MCALL statement, you must specify several .MCALL directives, each appearing on a 
separate source line. The availability of space within an 80-byte line of source code limits the 
number of such names that may appear in any one .MCALL statement. 


Format 
-MCALL §argl,arg2, ... ,argn 


Argument 


argl,arg2, ... ,argn 
Specifies a list of symbolic names that identify the macro definitions that you use in your 
program. If more than one source line is required to list the names of all desired macros, 
each additional line must begin with a .MCALL directive. 


For clarity in your source code, you may list the assembly-time, run-time, and file-processing 
macro names in each of three separate .MCALL statements; you may list the macro names 
alphabetically, or you may mix them. None of these optional arrangements have any effect 
whatever on retrieving macro definitions from the System Macro Library. 
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If you are planning to invoke the command line processing capabilities of the Get Command 
Line (GCML) routine and the Command String Interpreter (CSI), you must list all the names 
of the associated macros as arguments in a .MCALL directive. GCML and CSI, ordinarily 
employed in system or application programs for convenience in dynamically processing file 
specifications, are described in detail in Chapter 6. 


The .MCALL directive is described in detail in the PDP-11 MACRO-11 Language Reference 
Manual. The sample programs in Appendix J also illustrate the use of the .MCALL directive. 
Note that these .MCALL directives appear as the first statements in the preparatory coding of 
these programs. 


The object routines described in Chapter 4 should not be confused with the macro definitions 
available from the System Macro Library. The file control routines, constituting a body of 
object modules, are linked into your program at task-build time from the system object library 
([1,1]SYSLIB.OLB). Consult Chapter 4 for a description of these routines. 


The following statements show sample uses of the .MCALL directive: 


-MCALL FDBDF$,FDAT$A,FDRC$A, FDOP$A , NMBLK$ ,FSRSZ$ ,FINIT$ 
-MCALL OPENS$R, OPEN$W, GETS, PUT$ , CLOSE$ 


Note 


You can use the macro FCSMC$ to declare the most commonly used FCS macros within the 
-MCALL format as follows: 


-MCALL FCSMC$ 
FCSMC$ 


FCS macros declared in this manner include: OPEN$x, OPNS$x, CLOSE$, READ$, WRITE$, 
WAITS, GET$, PUT$, DELET$, FINIT$, FSRSZ$, FDBDF$, FDAT$x, FDRC$x, FDOP$x, FDBF$x, 
FDBK$x, and NMBLK$. If other macros are required, explicit MCALL directives must be issued. 
One disadvantage of using this method to declare .MCALL directives is that unused macros 
may take up possibly critical assembler symbol table space, thus slowing down the assembly 
process. 


2.3 File Descriptor Block 


The File Descriptor Block (FDB) is the data structure that provides the information FCS needs 
for all file I/O operations. Two sets of macro calls are available for FDB initialization: you can 
use one set for assembly-time initialization (see Section 2.3.1) and the other set for run-time 
initialization (see Section 2.3.2). Use the run-time macros to supplement or override information 
specified during assembly. The FDB sections are described in Appendixes A and B. 


2.3.1 Assembly-Time FDB Initialization Macros 


Assembly-time initialization requires that the FDBDF$ macro call be issued (see Section 2.3.1.1) 
to allocate space for and to define the beginning address of the FDB. Additional macro calls 
can then be issued to establish other required information in this structure. The assembly-time 
macros that accomplish these functions are described in the following sections. 


Format 
mcnam$A p1,p2,...,pn 
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Macro Name 


menam$A 
Specifies the symbolic name of the macro. 


Parameter 


pl,p2,...,pn 
Specifies the string of initialization parameters associated with the specified macro. A 
parameter may be omitted from the string by leaving its field between delimiting commas 
null. Assume, for example, that a macro call may take the following parameters: 


FDOP$A 2,DSPT,DFNB 


Assume further that the second parameter field is to be coded as a null specification. In 
this case, the statement is coded as follows: 


FDOP$A 2, ,DFNB 


A trailing comma need not be inserted to reflect the omission of a parameter beyond the 
last explicit specification. For example, the following macro call need not be specified as if 
the last parameter (DFNB) is omitted: 


FDOP$A 2,DSPT,DFNB 

FDOP$A 2,DSPT, 

Rather, such a macro call is specified as follows: 
FDOP$A 2,DSPT 


If any parameter is not specified, that is, if any field in the macro call contains a null specification, 
the corresponding cell in the FDB is not initialized and thus remains 0. 


Multiple values may be specified in a parameter field of certain macro calls. Such values 
are indicated by placing an exclamation point (!) between the values, indicating a logical OR 
operation to the MACRO-11 assembler. Specifying multiple values in this manner is mentioned 
throughout this manual if applicable to the macro call. 


Throughout the descriptions of the assembly-time macros in this section and elsewhere in 
this manual, symbols of the form F.xxx or F.xxxx are referenced (for example, F.RTYP). These 
symbols are defined as offsets from the beginning address of the FDB, allowing specific locations 
within the FDB to be referenced. Thus, you can reference or modify information within the 
FDB without having to calculate word or byte offsets to specific locations. 


Using such symbols in either system software or your software also permits the relative position 
of cells within the FDB to be changed (in a subsequent release, for example) without affecting 
your current programs or the coding style employed in developing new programs. As a result, 
we highly recommend that you use them. 
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2.3.1.1 FDBDF$—Allocate File Descriptor Block 


The FDBDF$ macro call is specified in a MACRO-11 program to allocate space within the 
program for an FDB. This macro call must be specified in the source program once for each 
input or output file that your program simultaneously opens during execution. Any associated 
assembly-time macro calls (see Sections 2.3.1.2 to 2.3.1.6) must then be specified immediately 
following the FDBDF$ macro if you want to initialize certain portions of this FDB during 
assembly. 


Macro Name and Label 
label: FDBDF$ 


label 
Specifies a symbol, which you specify, that names this particular FDB and defines its 
beginning address. This label is particularly significant in all I/O operations that require 
access to the data structure allocated through this macro call. FCS accesses the fields within 
the FDB relative to the address represented by this symbol. 


The following examples show how the FDBDF$ macro calls might appear in your source 
program: 


FDBOUT: FDBDF$ ; ALLOCATES SPACE FOR AN FDB NAMED 
;"FDBOUT" AND ESTABLISHES THE 
;BEGINNING ADDRESS OF THE FDB. 


FDBIN: FDBDF$ ; ALLOCATES SPACE FOR AN FDB NAMED 
;"FDBIN" AND ESTABLISHES THE 
;BEGINNING ADDRESS OF THE FDB. 


As noted earlier, the source program must embody one FDBDF$ macro call logically similar 
to these example macro calls for your program to access each file simultaneously. FDBs can 
be reused for many different files, as long as the file currently using the FDB is closed before 
the next file is opened. The only requirement is that an FDB must be defined for every 
simultaneously opened file. 


2.3.1.2 FDAT$A—Initialize File Attribute Section of FDB 


The FDAT$A macro call initializes the file attribute section of the FDB when a new output file is 
to be created. If the file to be processed already exists, the first four parameters of the FDAT$A 
initialization macro need not be specified because FCS obtains the necessary information from 
the first 14 bytes of the file attribute section. The file attribute section is in the header block of 
the specified file. (See Appendix C.) 


Format 


FDAT$A _rtyp,ratt,rsiz,cntg,aloc 
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Parameters 


rtyp 
Specifies a symbolic value that defines the type of records to be built as the new file is 
created. One of three values must be specified, as follows: 


R.FIX Indicates that fixed-length records are to be written in creating the file. 
R.VAR Indicates that variable-length records are to be written in creating the file. 
R.SEQ Indicates variable-length sequenced records are to be written in creating the file. 


The rtyp parameter initializes FDB offset location F.RTYP. The symbols R.FIX, R.VAR, and 
R.SEQ initialize the same location in the FDB and are mutually exclusive. 


ratt 
Specifies symbolic values that may be specified to define the attributes of the records as the 
new file is created. 


The following parameters initialize the record attribute byte (offset location F.RATT) 
in the FDB. The values FD.FTN and FD.CR are mutually exclusive and must not be 
specified together. Apart from this restriction, the combination (logical OR) of multiple 
parameters specified in this field must be separated by an exclamation point (for example, 
FD.CR!FD.BLK). 


The following symbolic values may be specified, as appropriate, to define the desired record 
attributes: 


FD.FTN Indicates that the first byte in each record will contain a FORTRAN carriage control 
character. 


FD.CR Indicates that the record is to be preceded by a <LF> character and followed by 
a <CR> character when the record is written to a carriage control device (for 
example, a line printer or a terminal). 


FD.BLK Indicates that records are not allowed to cross block boundaries. 


FD.PRN Indicates that the record is preceded by a word containing carriage control 
information; this value is the print file format attribute. Files that have this 
attribute set must also be sequenced files; that is, files that have the bit R.SEQ set 
in byte F.RTYP in the FDB. 


In a file with attribute FD.PRN, each record is associated with its own print format 
word, which describes the carriage control for that record, if the record is output to 
a unit record device such as a terminal or line printer. A program using FCS can 
read or write a file with attribute FD.PRN, but FCS ignores and does not interpret 
the format word. Thus, the Peripheral Interchange Program (PIP) correctly copies 
such a file from disk to disk, but a copy to TI may not achieve the desired carriage 
control. Note that FCS does not interpret the FD.PRN format word. 


Files with the print file format attribute are a subset of sequenced files. Sequenced 
files are identified by record type R.SEQ in FDB field R.RTYP. Sequenced files 
have records of variable length; each record is associated with a 1-word sequence 
number. (Note that sequential is not the same as sequenced. Sequential means 
that the file is not a Record Management Services (RMS) indexed or relative file. 
All sequenced files are also sequential.) 
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rsiz 


When a program is reading a sequenced file with FCS in record mode, FCS returns 
the record in the normal manner on a GET$; the sequence number is returned in 
FDB field F.SEQN. Conversely, when writing a sequenced file with FCS in record 
mode, FCS writes the record in the normal manner and writes the associated 
sequence number from F.SEQN. 


The sequence number field can contain any pattern of bits. A frequent application 
of this field is its use as a line number for text files. 


The difference between a file with attribute FD.PRN and any other sequenced file 
is that the sequence number is considered to be the carriage control format word. 
This word has a particular meaning in a file with attribute FD.PRN. Each byte 
of the format word describes the carriage control for the associated record. The 
low byte describes carriage control action that should occur before the record is 
printed; the high byte describes carriage control action that should occur after the 
record is printed. 


FCS operates on files with attribute FD.PRN in the same way that it operates on 
any other sequenced file. FCS uses the FDB field F.SEQN for the format word. 
Each byte of the format word is defined as follows: 


Bits 0-6 Bit7 Meaning 
eee 
0 0 No carriage control. 

1-127 0 Bits 0-6 are a count of 


line records. 


ros eee 


Bits 0-4 BitS Bit6 Bit7 Meaning 
= 


1-311 0 0 1 Bits 0-4 define a 7-bit 
ASCII control character to be output. 
1-314 1 0 1 Bits 0-4 are translated 


as an 8-bit ASCII control 
character ranging from 
1281 to 15949 to be output. 


0 1 1 1 Reserved for future use. 


Because print format files must be sequenced files, FCS allows FD.PRN as an 
attribute of a new file only if record type R.SEQ is also specified. For example: 


FDBDF$ :Allocate space for FDB 
FDAT$A :Print file format 


FCS does not create a file with attribute FD.PRN that has a record type other than 
R.SEQ. In this case, FCS returns an error ~45j9, IE.RAT, “illegal attribute bits set.” 


Specifies a numeric value that defines the size (in bytes) of fixed-length records to be written 
to the file. This value, which initializes FDB offset location F.RSIZ, need not be specified 
if R.VAR has been specified as the record type parameter (for variable-length records). If 
R.VAR or R.SEQ is specified, FCS maintains a value in FDB offset location F.RSIZ that 
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defines the size (in bytes) of the largest record currently written to the file. Thus, whenever 
an existing file containing variable-length records is opened, the value in F.RSIZ defines the 
size of the largest record within that file. By examining the value in this cell, a program 
can dynamically allocate record buffers for its open files. 


cntg 
Specifies a signed numeric value that defines the number of blocks that are allocated for 
the file as it is created. The signed values have the following significance: 


Positive Value Indicates that the specified number of blocks is to be allocated contigu- 
ously when the file is created; it also indicates that the file is to be 
contiguous. 


Negative Value _ Indicates that the two’s complement of the specified number of blocks is to 
be allocated when the file is created, though not necessarily contiguously; 
it also indicates that the file is to be noncontiguous. 


The cntg parameter, which has 15 bits of magnitude (plus a sign bit), initializes FDB offset 
location F.CNTG. 


(You can specify an allocation of up to 24 bits by using the .EXTND routine.) 


If you can estimate how long the file might be, it is more efficient to allocate the required 
number of blocks through this parameter when the file is created than to require FCS to 
extend the file when the file is written. (See the aloc parameter in the following text.) 


If this parameter is not specified, an empty file is created; that is, no space is allocated 
within the file as it is created. 


Issuing the CLOSE$ macro call at the completion of file processing resets the value in 
E.CNTG to 0. Thus, the usual procedure is to initialize this location at run time just before 
opening the file. Reinitialization is necessary if the FDB is reused. 


aloc 
Specifies a signed numeric value that defines the number of blocks by which the file is 
extended, if FCS determines that file extension is necessary as records are written to the 
file. When the end of allocated space in the file is reached during writing, the signed value 
provided through this parameter causes file extension to occur, as follows: 


Positive Value Indicates that the specified number of blocks is to be allocated contigu- 
ously as additional space within the file; it also indicates that the file is 
to be contiguous. 


Negative Value Indicates that the two’s complement of the specified number of blocks is 
to be allocated noncontiguously as additional space within the file; it also 
indicates that the file is to be noncontiguous. 


Note 


Once a file has had blocks allocated, all future file extensions cause the file 
to become noncontiguous, even when aloc is a positive value. 
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This parameter, which also has 15 bits of magnitude (plus a sign bit), initializes FDB offset 
location F.ALOC. If this optional parameter is not specified, file extension occurs as follows: 


¢ If the number of virtual blocks yet to be written is greater than 1, the file is extended 
by the exact number of blocks required to complete the writing of the file. 


¢ If only one additional block is required to complete the writing of the file, the file is 
extended in accordance with the volume’s default extend value. 


The volume default extend size is established through the INITIALIZE or MOUNT command. 
The volume default extend size cannot be established at the FCS level; this value must be 
established when the volume is initially mounted. 


The following example statement shows a sample of an FDAT$A macro call. This statement 
initializes the FDB in preparation for creating a new file containing fixed-length, 80-byte records 
that will be allowed to cross block boundaries. For example: 


FDAT$A R.FIX,,80. 


In the previous example statement, the record attribute (ratt) parameter has been omitted, 
as indicated by the second comma (,) in the parameter string. Also, the cntg and aloc 
parameters have been omitted. Their omission, however, follows the last explicit specification, 
and their absence need not be indicated by trailing commas in the parameter string. Because 
the aloc parameter has been omitted, file extension (if it becomes necessary) is accomplished in 
accordance with the current default extend size in effect for the associated volume. 


If more than one record attribute is specified in the ratt parameter field, such specifications must 
be separated by an exclamation point (!), as shown in the following macro: 


FDAT$A R.VAR,FD.FTN!FD.BLK 


The previous macro call enables a file of variable-length records to be created. The records will 
contain FORTRAN vertical-formatting information for carriage control devices; the records will 
not be allowed to cross block boundaries. 


2.3.1.3 FDRC$A—Initialize Record Access Section of FDB 


The FDRC$A macro call initializes the record access section of the FDB, and the macro indicates 
whether to use record or block I/O operations in processing the associated file. 


If you want to use record I/O operations (GET$ and PUT$ macro, the FDRC$A or the FDRC$R 
macro call (see Section 2.3.2) establishes the FDB information necessary for record-oriented 
I/O. However, if you want to use block I/O operations (READ$ and WRITE$ macro calls), the 
FDBK$A macro call (see Section 2.3.1.4) or the FDBK$R macro call (see Section 2.3.2) must 
also be specified to establish other values in the FDB required for block I/O. In this case, 
portions of the record access section of the FDB are physically overlaid with parameters from 
the FDBK$A/FDBK$R macro call. 


You must appropriately initialize the FDB to indicate whether record or block I /O operations are 
to process the associated file prior to issuing the OPEN$ macro call to initialize file operations. 


Format 
FDRC$A __ racc,urba,urbs 
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Parameters 


race 
Specifies which variation of block or record I/O is to process the file. This parameter 
initializes the record access byte (offset location F.RACC) in the FDB. The first value shown 
next, FD.RWM, applies only for block I/O (READ$ or WRITE$) operations; all remaining 
values are specific to the following record I/O (GET$ or PUT$) operations: 


ED.RWM Indicates that READ$ or WRITE$ (block I/O) operations are to process the file. 

If this value is not specified, GET$ or PUT$ (record I/O) operations process the 
file by default. 
Specifying FD.RWM necessitates issuing an FDBK$A or an FDBK$R macro call in 
the program to initialize other offsets in the block access section of the FDB. Note 
also that the READ$ or WRITE$ macro call allows the complete specification of 
all the parameters required for block I/O operations. 


FD.RAN Indicates that random access mode is to process the file. If this value is not 
specified, sequential access mode processes the file by default. See Chapter 1 for 
a description of random access mode. 


The following statement shows a sample FDRC$A macro call issued for a file 
that may be accessed in random mode: 


FDRC$A FD.RAN,BUF1,160. 


You specify the address of the task’s record buffer through the symbol BUF1, 
and you specify the size of the buffer (in bytes) by the numeric value 160i. 


FD.PLC Indicates that locate mode is to process the file. If this value is not specified, 
move mode processes the file. 


FD.INS Indicates that a PUT$ operation performed within the body of the file shall not 
truncate the file. This value applies only for sequential files and therefore cannot 
be specified jointly with the FD.RAN parameter. 


If you specify more than one value in the record access (racc) field, an exclamation 
point (!) must separate the multiple values, as follows: 


FDRC$A FD.RAN!FD.PLC,BUF1,160. 


In addition to the functions described for the previous example, this example specifies that 
locate mode is to process the associated file. Note that the multiple parameters specified in 
the first field are separated by an exclamation point. 


If you want your task to perform a PUT$ operation within the body of a file, the POINT 
routine described in Chapter 4 may be called. This routine positions the file to a byte you 
specify within a virtual block in preparation for the PUT$ operation. The .POINT routine 
also permits a limited degree of random access to a file. 


If FD.INS is not specified, a PUT$ operation within the file truncates the file at the point 
of insertion; that is, the PUT$ operation moves the logical end-of-file (EOF) to a point just 
beyond the inserted record. However, no deallocation of blocks within the file occurs. 


Regardless of the setting of the FD.INS bit, a PUT$ operation that is in fact beyond the 
current logical end-of-file resets the logical end of the file to a point just beyond the inserted 
record. 
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urba 
Specifies the symbolic address of your task’s record buffer used for GET$ operations in 
move and locate modes; it is also used for PUT$ operations in locate mode. This parameter 
initializes FDB offset location F.URBD+2, and urba is specified only for record I/O operations. 


urbs 
Specifies a numeric value that defines the size (in bytes) of your task’s record buffer used 
for GET$ operations in move and locate modes; it is also used for PUT$ operations in locate 
mode. This parameter initializes FDB offset location F.URBD, and urbs is specified only for 
record I/O operations. 


You allocate and label a record buffer in a program by issuing a .,BLKB or .BLKW directive. The 
address and the size of this area are then passed to FCS as the urba and the urbs parameters 
shown previously. For example, a task’s record buffer may be defined through a statement that 
is logically equivalent to the following: 


RECBUF: .BLKB 82. 
RECBUF is the address of the buffer and 8239 is its size (in bytes). 


Beginning a task’s record buffers on a word boundary can improve performance by allowing 
FCS to move the data with MOV instructions rather than MOVB instructions. 


Under certain conditions, you need not allocate a record buffer or specify the buffer descriptors 
(urba and urbs) for GET$ or PUT$ operations. These conditions are described in detail in 
Chapter 3. 


2.3.1.4 FDBKSA—Initialize Block Access Section of FDB 


The FDBK$A macro call initializes the block access section of the FDB when block I/O operations 
(READ$ and WRITE$ macro calls) are used for file processing. Initializing the FDB with this 
macro call allows you to read or write virtual blocks of data within a file. 


Use of the FDBK$A macro call implies that the FDRC$A macro call has also been specified, 
because the FD.RWM parameter of the FDRC$A macro call initially declares block I/O 
operations. Thus, for block I/O operations, the FDRC$A macro call must be specified, as 
well as any one of the following macro calls, to appropriately initialize the block access section 
of the FDB: FDBK$A, FDBK$R, READ$, or WRITE$. 


Issuing the FDBK$A macro call causes certain portions of the record access section of the FDB to 
be overlaid with parameters necessary for block I/O operations. Thus, the terms “record access 
section” and “block access section” refer to a shared physical area of the FDB that is functional 
for either record or block I/O operations. 


The block I/O and record I/O FDB-initialization macros use the same area of the FDB for 
different data. Therefore, if record 1/O operations are to be employed, neither the FDBK$A nor 
the FDBK$R macro call must be issued. 


Format 
FDBK$A __ bkda,bkds,bkvb,bkef,bkst,bkdn 
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Parameters 


bkda 
Specifies the symbolic address of an area in your task’s memory space to be employed as a 
buffer for block I/O operations. This parameter initializes FDB offset location F.BKDS+2. 


bkds 
Indicates a numeric value that specifies the size (in bytes) of the block to be read or 
written when a block I/O request (READ$ or WRITE$ macro call) is issued. This parameter 
initializes FDB offset location F.BKDS. The size specified must be an even, positive (the sign 
bit must not be set) value; the maximum number of bytes that can be specified is 32,766. 
If an integral number of blocks is to be specified, the practical maximum number of bytes 
that can be specified is equal to 63 virtual blocks, or 32,2569 bytes. 


bkvb 

Specifies a dummy parameter for compatibility with the FDBK$R macro call. The bkvb 
parameter is not specified in the FDBK$A macro call for the reasons stated in item 4 of 
Section 2.3.2.1. In short, assembly-time initialization of FDB offset locations F.BKVB+2 and 
F.BKVB with a virtual block number is meaningless, because any version of the generalized 
OPEN$x macro call resets the virtual block number to 1 as the file is opened. Therefore, 
these cells can be initialized only at run time through either the FDBK$R macro call (see 
Section 2.3.2) or the I/O-initiating READ$ and WRITE$ macro calls (see Chapter 3). 


This dummy parameter should be reflected as a null specification (with a comma) in the 
parameter string only in the event that an explicit parameter follows. This null specification 
is required to maintain the proper position of any remaining field or fields in the parameter 
string. 


bkef 
Specifies a numeric value that specifies an event flag to be used during READ$ or WRITES 
operations to indicate the completion of a block I/O transfer. This parameter initializes FDB 
offset location F.BKEF; if not specified, event flag 3249 is used by default. 


The function of an event flag is described in further detail in Section 2.9.1. 


bkst 
Specifies the symbolic address of a 2-word I/O status block (IOSB) in your program. If 
specified, this optional parameter initializes FDB offset location F.BKST. 


The IOSB, if it is to be used, must be defined and appropriately labeled at assembly time. 
Then, if you specify the bkst parameter, information is returned by the system to the IOSB 
at the completion of the block I/O transfer. This information reflects the status of the 
requested operation. If this parameter is not specified, no information is returned to the 
IOSB. 


Note 
If an error occurs during a READ$ or WRITES operation that would normally 
be reported as a negative value in the first byte of the IOSB, the error is not 
reported unless you specify an IOSB address. You are advised to specify 
this parameter, which allows the return of block I/O status information and 
permits normal error reporting. 
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The creation and function of the IOSB are described in detail in Section 2.9.2. 


bkdn 
Specifies the symbolic address of an optional asynchronous system trap (AST) service 
routine, which you code. If present, this parameter causes the AST service routine to be 
initiated at the specified address upon completion of block I/O; if not specified, no AST 
trap occurs. This parameter initializes File Descriptor Block (FDB) offset location F.BKDN. 


Considerations relevant to the use of an AST service routine are presented in Section 2.9.3. 


The following example shows an FDBK$A macro call that uses all available parameter fields for 
initializing the block access section of the FDB: 


FDBK$A BKBUF ,240.,,20., ISTAT, ASTADR 


In this macro call, the symbol BKBUF identifies a block I/O buffer reserved in your program 
that will accommodate a 240j9-byte block. The virtual block number is null (for the reasons 
stated previously in the description of this parameter), and the event flag to be set upon block 
I/O completion is 20;9. Finally, the symbol ISTAT specifies the address of the IOSB, and the 
symbol ASTADR specifies the entry point address of the AST service routine. 


2.3.1.5 FDOPSA—Initialize File-Open Section of FDB 


The FDOP$A macro call initializes the file-open section of the FDB. In addition to a logical unit 
number (LUN), you would normally specify a data-set descriptor pointer, a default filename 
block address, or both, for each file that is to be opened. The latter two parameters provide 
FCS with the linkage necessary to retrieve file specifications from these data structures that you 
created in the program. 


Although both a data-set descriptor pointer (dspt) and the address of a default filename block 
(dfnb) may be specified for a given file, one or the other must be present in the FDB before that 
file can be opened. If, however, certain information is already present in the filename block as 
the result of prior program action, neither the data-set descriptor nor the default filename block 
is accessed by FCS, and you can open the file using a process called “opening a file by file ID.” 
This process, which is an efficient method of opening a file, is described in detail in Section 2.6. 


The dspt and dfnb parameters represent address values that point to data structures that you 
created in the program. These data structures, which are described in detail in Section 2.5, 
provide file specifications to the File Control Services (FCS) file-processing routines. 


Format 
FDOP$A __lun,dspt,dfnb,facc,actl 


Parameter 


lun 
Specifies a numeric value that specifies a logical unit number (LUN). This parameter 
initializes FDB offset location F.LUN. All I/O operations performed with this FDB are done 
through the specified LUN. Every active FDB must have a unique LUN. 
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The LUN specified through this parameter may be any value from 1 through the largest 
value specified to the Task Builder through the UNITS option. This option specifies the 
number of logical units that the task is to use (see the RSX-11M-PLUS and Micro/RSX Task 
Builder Manual.) 


dspt 
Specifies the symbolic address of a 6-word block in your task containing the data-set 
descriptor. This data structure, which you created, consists of a 2-word device descriptor, a 
2-word directory descriptor, and a 2-word file name descriptor, as outlined in Section 2.5.1. 


The dspt parameter initializes FDB offset location F.DSPT. This address value, called the 
data-set descriptor pointer, is the linkage address through which FCS accesses the fields in 
the data-set descriptor. 


When the Command String Interpreter (CSI) processes command string input, a file 
specification is returned to the calling program in a format identical to that nf the manually 
created data-set descriptor. The use of CSI as a dynamic command line processor is 
described in detail in Chapter 6. 


dfnb 
Specifies the symbolic address of the default filename block. This structure is allocated 
within your task through the NMBLK$ macro call (see Section 2.5.2). When specified, the 
dfnb parameter initializes FDB offset location F.DFNB, allowing FCS to access the fields of 
the default filename block in building the filename block in the FDB. 


Specifying the dfnb parameter in the FDOP$A (or the FDOP$R) macro call assumes that 
the NMBLK$ macro call has been issued in the program. Furthermore, the symbol specified 
as the dfnb parameter in the FDOP$A (or the FDOP$R) macro call must correspond exactly 
to the symbol specified in the label field of the NMBLK$ macro call. 


face 
Specifies any one, or any appropriate combination, of the following symbolic values 
indicating how the specified file is to be accessed: 


FO.RD Indicates that an existing file is to be opened for reading only. 

FO.WRT Indicates that a new file is to be created and opened for writing. 

FO.APD Indicates that an existing file is to be opened and appended. 

FO.MFY Indicates that an existing file is to be opened and modified. 

FO.UPD Indicates that an existing file is to be opened, updated, and, if necessary, extended. 


FA.NSP Indicates, in combination with FO.WRT, that an old file having the same file 
specification is not to be superseded by the new file. Rather, an error code is to 
be returned if a file of the same file name, type, and version exists. 


FA.TMP Indicates, in combination with FO.WRT, that the created file is to be a temporary 
file. 


FA.SHR Indicates that the file is to be opened for shared access. Shared access is also a 
precondition for block locking. 
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The facc parameter initializes FDB offset location F.FACC. The symbolic values FO.xxx, 
described previously, represent the logical OR of bits in FDB location F.FACC. 


The information specified by this parameter can be overridden by an OPEN$ macro call, as 
described in Section 3.7. It is overridden by an OPEN$x macro call. 


act 


Specifies a symbolic value that specifies the following control information in FDB location 
F.ACTL: 


* Magnetic tape position. 

¢ Whether a disk file that is opened for write is to be locked if it is not properly closed; 
for example, the file may not be properly closed if the task terminates abnormally. 

* Number of retrieval pointers to allocate for a disk file window. 

¢ Whether to enable block locking. 


Normally, FCS supplies default values for F.ACTL. However, if FA.ENB is specified in 
combination with any of the symbolic values described in the following text, FCS uses the 
information in F.ACTL. The FA.ENB location must be specified with the desired values to 
override the defaults. The following are the defaults for location F.ACTL: 


¢ For file creation, magnetic tapes are positioned to the end of the volume set. 
* At file open and close, tapes are not rewound. 

* A disk file that is opened for write is locked if it is not properly closed. 

* The volume default is used for the file window. 

The following values can be used with FA.ENB: 


FA.POS Is meaningful only for output files and is specified to cause a magnetic 
tape to be positioned just after the most recently closed file for creating 
a new file. Any files that exist after that point are lost. If rewind is 
specified, it takes precedence over FA.POS, thus causing the tape to be 
positioned just after the VOL1 label for file creation. See Chapter 5 for 
more information on tape positioning. 


FA.RWD Is specified to cause a magnetic tape to be rewound when the file is 
opened or closed. 


Examples of using FA-ENB with FA.POS and FA.RWD are provided in 
Chapter 5. 
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FA.DLK Is specified to cause a disk file not to be locked if it is not properly closed. 
The number of retrieval pointers for a file window can be specified in the 
low-order byte of F.ACTL. The default number of retrieval pointers is the 
file-window mapping pointer count parameter (/WIN) included in the 
Monitor Console Routine (MCR) commands INI or MOUNT (DIGITAL 
Command Language (DCL) commands, INITIALIZE and MOUNT); the 
default value for this parameter is 7. Retrieval pointers point to contiguous 
blocks of the file on disk. Access to fragmented files may be optimized by 
increasing the number of retrieval pointers, that is, by increasing the size 
of the window. Similarly, because retrieval pointers use up pool space, 
additional memory can be freed up by reducing the number of pointers 
for files with little or no fragmentation—for example, contiguous files. 


FA.LKL!FA.EXL Is specified to lock all accessed blocks. FCS permits limited block locking 
to coordinate the access of the same file by two or more tasks. All 
tasks accessing the file must open the file for shared access by setting bit 
FA.SHR in FDB field F.FACC (the field access byte). 

See the RSX-11M-PLUS and Micro/RSX I/O Drivers Reference Manual for 
further information on block locking. Also, see Section 2.9.4 of this 
manual. 


As noted, if neither the dspt nor the dfnb parameter is specified, the corresponding offset 
locations F.DSPT and F.DFNB contain 0. In this case, no file is currently associated with this 
FDB. Any attempt to open a file with this FDB results in an open failure. Either offset location 
F.DSPT or F.DFNB must be initialized with an appropriate address value before a file can 
be opened using this FDB. Normally, these cells are initialized at assembly time through the 
FDOP$A macro call; but they may also be initialized at run time through the FDOP$R or the 
generalized OPEN$x macro call (see Chapter 3). 


The examples at the end of this section show how the FDOP$A macro call may be used in 
your source program. 


Examples 
FDOP$A 1,,DFNB 


Indicates that the data-set descriptor pointer parameter (dspt) is null, requiring that FCS rely 
on the run-time specification of the data-set descriptor pointer for the FDB or the use of the 
default filename block for required file information. 


FDOP$A 2,0FDSPT 


Specifies a data-set descriptor pointer (named OFDSPT), which allows FCS to access the fields 
in the data-set descriptor for required file information. 


FDOP$A 2,0FDSPT,DFNB 


Specifies both a data-set descriptor pointer and a default filename block address, which causes 
FDB offset locations F.DSPT and F.DFNB, respectively, to be initialized with the appropriate 
values. In this case, FCS can access the data-set descriptor and the default filename block, 
or both, for required file information. By convention, FCS first seeks such information in the 
data-set descriptor; if all the required information is not present in this data structure, FCS 
attempts to obtain the missing information from the default filename block. 
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FDOP$A 1,CSIBLK+C.DSDS 


Shows a macro call that takes as its second parameter a symbolic value that causes FDB offset 
location F.DSPT to be initialized with the address of the CSI data-set descriptor. This structure 
is created in the CSI control block by invoking the CSI$ macro call. All considerations relevant 
to the use of CSI as a dynamic command line processor are presented in Chapter 6. 


FDOP$A 1,,DFNB, ,FA.ENB!16. 


Shows the use of the actl parameter to increase the number of retrieval pointers in the file 
window to 16. FA.ENB causes the contents of F.ACTL, rather than the defaults, to be used. 


In all the examples previously shown, the value specified as the first parameter supplies the 
logical unit number (LUN) used for all I/O operations involving the associated file. 


2.3.1.6 FDBFSA—Initialize Block Buffer Section of FDB 


The FDBF$A macro call initializes the block buffer section of the FDB when record I /O operations 
(GET$ and PUT$ macro calls) process files. Initializing the FDB with this macro call allows FCS 
to control the necessary blocking and deblocking of individual records within a virtual block as 
an integral function of processing the file. 


Format 
FDBF$A efn,ovbs,mbct,mbfg 


efn 
Indicates a numeric value that specifies the event flag that FCS uses to synchronize record 
I/O operations. This numeric value initializes FDB offset location F.EFN. FCS uses this 
event flag internally; you must not set, clear, or test it, 


If this parameter is not specified, FCS uses event flag 32i9. A null specification in this field 
is indicated by inserting a leading comma in the parameter string. 


ovbs 
Indicates a numeric value that specifies a file storage region (FSR) block buffer size, in bytes, 
that overrides the standard block size for the particular device associated with the file. This 
parameter initializes FDB offset location F.OVBS with the specified block buffer size. 


When you use ovbs to specify an FSR block buffer size for disks, specify the desired number 
of bytes in integral multiples of 512j9 bytes, overriding the one-sector, standard 512,9-byte 
block buffer size. You can specify block buffer sizes up to 63 sectors (32,25619 bytes) 
for disks. Increasing the block buffer size in this manner greatly reduces average disk 
access time because several contiguous sectors are generally read or written during a typical 
disk access operation. An override block size of 204849 bytes (4 sectors) or 25601) bytes 
(5 sectors) is recommended because 204819 bytes also provides American National Standards 
Institute (ANSI) magnetic tape buffer capability, and 256049 bytes is the Files—11 default 
extend size. Note that once the file has been opened, FCS uses the ovbs field for other 
purposes. Thus, if your task uses the FDB for additional disk I/O operations, the ovbs 
parameter must be issued in an FDBF$R macro prior to accessing the disk. 


Preparing for1/O 2-17 


Note 


When you specify block buffer sizes greater than one sector (51219 bytes), 
you must increase accordingly the size of $$FSR1. This is done by specifying 
an appropriate value for the bufsiz parameter in the FSRSZ$ macro call (see 
Section 2.7.1). 


Routines that read ANSI-standard magnetic tape without prior knowledge of the format 
of the files to be read must specify an override block size of 819219 bytes. This value is 
sufficient for the largest ANSI-standard tape blocks. 


Issuing the CLOSE$ macro call (see Chapter 3) resets offset location F.OVBS in the associated 
FDB to 0. Therefore, this location should typically be initialized at run time, just before 
opening the file, particularly if an OPEN$x/ CLOSE$ sequence for the file is performed more 
than once. 


On certain devices, such as line printers and terminals, the block size should not exceed the 
device’s line width. The task can obtain the proper block size for these devices by issuing 
the Get LUN Information system directive for each device. (See the description for the 
Get LUN Information directive in the RSX-11M-PLUS and Micro/RSX Executive Reference 
Manual. The standard block size for each device is established at system generation time or 
by the MCR command SET/BUF. 


mbct 
Indicates a numeric value that specifies the multiple buffer count, that is, the number of 
buffers FCS uses in processing the associated file. This parameter initializes FDB offset 
location F.MBCT. If this value is greater than 1, multibuffering is effectively declared for 
file processing. In this case, FCS employs either read-ahead or write-behind operations, 
depending on which of two symbolic values is specified as the mbfg parameter (see the 
following entry). 


If the mbct parameter is specified as null or 0, FCS uses the default buffer count contained 
in symbolic location A.DFBC in $$FSR2 (the program section in the FSR containing impure 
data). This cell normally contains a default buffer count of 1. If desired, this value can be 
modified, as noted in the discussion of the mbfg parameter in the following entry. 


If, in specifying the FSRSZ$ macro call (see Section 2.7.1), sufficient memory space has not 
been allocated to accommodate the number of buffers established by the mbct parameter, 
FCS allocates as many buffers as can fit in the available space. Insufficient space for at least 
one buffer causes FCS to return an error code to FDB offset location F.ERR. 


You can initialize the buffer count in F.MBCT through either the FDBF$A or the FDBF$R 
macro call. The buffer count so established is not altered by FCS and, once set, need not 
be of further concern to you. 


When input is from record devices (for example, a card reader), F.MBCT should not be 
greater than 2. 


mbfg 
Specifies a symbolic value that specifies the type of multibuffering to be employed in 
processing the file. Either of the following two values may be specified to initialize FDB 
offset location F.MBFG: 
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FD.RAH Indicates that read-ahead operations are to be used in processing the file 
FD.WBH Indicates that write-behind operations are to be used in processing the file 


These parameters are mutually exclusive; that is, one or the other, but not both, may be 
specified. 


Specifying this parameter assumes that the buffer count established in the mbct parameter 
shown previously is greater than 1. If multibuffering has thus been declared, omitting the 
mbfg parameter causes FCS to use read-ahead operations by default for all files opened 
using the OPEN$R macro call; similarly, FCS uses write-behind operations by default for 
all files opened using other forms of the OPEN$x macro call. 


If these default buffering conventions are not desired, you can alter the value in the F.MBFG 
dynamically at run time. This is done by issuing the FDBF$R macro call, which takes as 
the mbfg parameter the appropriate control flag (FD.RAH or FD.WBH). This action must be 
taken, however, before opening the file. 


Offset location F.MBFG in the FDB is reset to 0 each time the associated file is closed. 


Note 


When using write-behind multibuffering, there is no gain in efficiency if the 
size of the file must be increased to make room for the data to be written. 
If a file is being written at the end, using default extension, there will be 
one extend operation for each five write operations; thus, only 80% of the 
write-behind operations will actually be overlapped with processing. This 
percentage can be increased as follows: 


° Space for the file can be completely preallocated, either by using the cntg 
parameter in the FDAT$A macro, or by using the EXTND subroutine. 


* The default extension amount can be increased from five blocks by using 
the aloc parameter of the FDAT$A macro call. For example, if an aloc 
parameter of 10;9 is specified, the number of write-behind operations 
that will be overlapped will increase to 90%. 


° The file can be accessed using random I/O. Because issuing PUT$R 
macros to access random preexisting locations in the file does not require 
extends, the percentage of overlapped operations is increased. 


You can change the default buffer count, if desired, by modifying a location in $$FSR2, which 
is the second of two program sections comprising the FSR. A location defined as .MBFCT in 
$$FSR2 normally contains a default buffer count of 1. This default value may be changed, as 
follows: 


Apply a global patch to A.DFBC at task-build time to specify the desired number of buffers. 


For MACRO-11 programs, use the EXTSCT option of the Task Builder (see Section 2.8.1) 
to allocate more space for the FSR block buffers; for FORTRAN programs, use the ACTFIL 
option of the Task Builder (see Section 2.8.2) to allocate more space for the FSR block 
buffers. 
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Because the previous procedure alters the default buffer count for all files to be processed by 
your program, it may be desirable to force single buffering for any specific file or files that 
would not benefit from multibuffering. In such a case, you can set the buffer count in F.MBCT 
for a specific file to 1 by issuing the following example macro call for the applicable FDB: 


FDBF$A ,,t 


The value 1 specifies the buffer count (mbct) for the desired file and is entered into offset 
location F.MBCT in the applicable FDB. Note in the previous example that the event flag 
(efn) and the override block buffer size (ovbs) parameters are null; these null values are 
for illustrative purposes only and should not be interpreted as conditional specifications for 
establishing single-buffered operations. 


The following examples show how the FDBF$A macro call may be used in a program. 


Examples 
FDBF$A 25.,,1 


Specifies that event flag 2519 synchronizes record I/O operations and that single buffering is 
used in processing the file. 


FDBF$A 25.,,2,FD.RAH 


Specifies event flag 2519 for synchronizing record I/O operations and, in addition, establishes 2 
as the multiple buffer count. The buffers so specified are for read-ahead operations, as indicated 
by the final parameter. 


FDBF$A ,,2,FD.WBH 


Allows event flag 3219 to be used by default for synchronizing record I/O operations, and the 
two buffers specified in this case are for write-behind operations. 


Note in all three examples that the second parameter, that is, the override block size parameter 
(ovbs), is null; thus, the standard block size in effect for the device in question is used for all 
file 1/O operations. 


2.3.2 Run-Time FDB Initialization Macros 


Although the FDB is allocated and can be initialized during program assembly, the contents of 
specific sections of the FDB can also be initialized or changed at run time by issuing any of the 
following macro calls: 


FDAT$R __Initializes or alters the file attribute section of the FDB. 
FDRC$R_ Initializes or alters the record access section of the FDB. 


FDBK$R __Initializes or alters the block access section of the FDB (see item 4 in Section 2.3.2.1 
following). 


FDOP$R __Initializes or alters the file-open section of the FDB. 
FDBF$R Initializes or alters the block buffer section of the FDB. 


There are no default values for run-time FDB macros (except for the FDB address). At run time, 
the values currently in the FDB are used unless they are explicitly overridden. For example, 
values stored in the FDB at assembly time are used at run time unless they are overridden. The 
run-time FDB macros place the FDB address in RO. 
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2.3.2.1 Run-Time FDB Macro Exceptions 


The format and the parameters of the run-time FDB initialization macros are identical to the 
assembly-time macros described earlier, except as noted here: 


An R rather than an A must appear as the last character in the run-time symbolic macro 
name. 


The first parameter in all run-time macro calls must be the address of the FDB associated 
with the file to be processed. All other parameters in the run-time macro calls are identical 
to those described in Sections 2.3.1.2 to 2.3.1.6 for the assembly-time macro calls, except as 
noted in items 3 and 4 in this section. 


The parameters in the run-time macro calls must be valid MACRO-11 source operand 
expressions. These parameters may be address values or literal values; they may also 
represent the contents of registers or memory locations. In short, any value that is a valid 
source operand in a MOV or MOVB instruction may be specified in a run-time macro call. 
In this regard, the following conventions apply: 


— If the parameter is an address value or a literal value that is to be placed in the FDB, 
that is, if the parameter itself is to be taken as an argument, it must be preceded by the 
number sign (#). This symbol is the immediate expression indicator for MACRO-11 
programs, causing the associated argument to be taken literally in initializing the 
appropriate cell in the FDB. Such literal values may be specified as follows: 


FDOP$R #FDBADR,#1,#DSPT, #DFNB 


- If the parameter is the address of a location containing an argument that is to be placed 
in the FDB, the parameter must not be preceded by the number sign. Such a parameter 
may be specified as follows: 


ONE: . WORD 1 


FDOP$R #FDBADR,ONE,#DSPT,#DFNB 


ONE represents the symbolic address of a location containing the desired initializing 
value. 


— If the parameter is a register specifier (for example, R4), the parameter must not be 
preceded by the number sign. Register specifiers are defined MACRO-11 symbols and 
are valid expressions in any context. 


Note 
RO can only be specified in the first parameter (FDB address). Any other 
use of RO will fail. (See Section 2.3.2.2.) 


Thus, in contrast, parameters specified in assembly-time macro calls are used as arguments 
in generating data in .WORD or .BYTE directives, while parameters specified in run-time 
macro calls are used as arguments in MOV and MOVB machine instructions. 
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e As noted in the description of the FDBK$A macro call in Section 2.3.1.4, assembly-time 
initialization of the FDB with the virtual block number is meaningless because issuing the 
OPEN$x macro call to prepare a file for processing resets the virtual block number in the 
FDB to 1. For this reason, the virtual block number can be specified only at run time after 
the file has been opened. Do this by issuing either the FDBK$R macro call or the I/O- 
initiating READ$ or WRITE$ macro call. In all three cases, the relevant field for defining 
the virtual block number is the bkvb parameter. The READ$ and WRITE$ macro calls are 
described in detail in Chapter 3. 


At assembly time, you must reserve and label a 2-word block in the program to temporarily 
store the virtual block number appropriate for intended block I/O operations, Because your 
task is free to manipulate the contents of these two locations at will, any virtual block 
number consistent with intended block I/O operations may be defined. By specifying the 
symbolic address (that is, the label) of this field as the bkvb parameter in the selected 
run-time macro call, you can make the virtual block number available to FCS. 


In preparing for block I/O operations, you must follow these procedures: 


1. At assembly time, reserve a 2-word block in your program through a statement that is 
logically equivalent to the following: 


VBNADR: .BLKW 2 


The label VBNADR names this 2-word block and defines its address. This symbol 
is used subsequently as the bkvb parameter in the selected run-time macro call for 
initializing the FDB. 

2. At run time, load this field with the desired virtual block number. This operation may 
be accomplished through statements logically equivalent to the following: 


CLR VBNADR 
MOV #10400 , VBNADR+2 


Note that the first word of the block is cleared. The MOV instruction then loads the 
second (low-order) word of the block with a numeric value. This value constitutes the 
16 least significant bits of the virtual block number. 


If the desired virtual block number cannot be completely expressed within 16 bits, the 
remaining portion of the virtual block number must be stored in the first (high-order) 
word of the block. This may be accomplished through statements logically equivalent 
to the following: 


MOV #1, VBNADR 
MOV #10400 , VBNADR+2 


As a result of these two instructions, 31 bits of value are defined in this 2-word block. 
The first word contains the 15 most significant bits of the virtual block number, and the 
second word contains the 16 least significant bits. Thus, the virtual block number is an 
unsigned value having 31 bits of magnitude. You must ensure that the sign bit in the 
high-order word is not set. 


3. Open the desired file for processing by issuing the appropriate version of the generalized 
OPEN$x macro call (see Chapter 3). 


4. Issue either the FDBK$R macro call or the READ$ or WRITE$ macro call, as appropriate, 
to initialize the relevant FDB with the desired virtual block number. 
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If the FDBK$R macro call is elected, the following is a representative example: 
FDBK$R #FDBIN,,,#VBNADR 


Regardless of the particular macro call that supplies the virtual block number, the two 
words at VBNADR are loaded into F.BKVB and F.BKVB+2. The first of these words 
(F.BKVB) is 0 if 16 bits are sufficient to express the desired virtual block number. The 
1/O-initiating READ$ or WRITE$ macro call may then be issued. 


Should you choose, however, to initialize the FDB directly through either the READ$ 
or WRITE$ macro call, the virtual block number may be made available to FCS through 
a statement such as the following: 


READ$ #FDBIN, #INBUF ,#BUFSIZ,#VBNADR 


The symbol VBNADR represents the address of the 2-word block in your program 
containing the virtual block number. 


2.3.2.2 Specifying the FDB Address in Run-Time Macros 


In relation to the second item of exceptions noted previously, the address of the File Descriptor 
Block (FDB) associated with the file to be processed corresponds to the address value of 
the symbol that you defined appearing in the label field of the FDBDF$ macro call (see 
Section 2.3.1.1). For example, the following statement not only allocates space for an FDB 
at assembly time, but it also binds the label FDBOUT to the beginning address of the FDB 
associated with this file: 


FDBOUT: FDBDF$ 


The address value so established can then be specified as the initial parameter in a run-time 
macro call in any one of the following three ways: 


1, 


The address of the appropriate FDB may be specified as an explicit parameter in a run-time 
macro call, as indicated in the following example statement: 


FDAT$R #FDBOUT,#R.VAR,#FD.CR 


The argument FDBOUT is taken literally by File Control Services (FCS) as the address of 
an FDB; furthermore, this address value, by convention, is stored in general register 0 (RO). 
Whenever this method of specifying the FDB address is employed, the previous contents 
of RO are overwritten (and thus destroyed). Therefore, you must exercise care in issuing 
subsequent run-time macro calls to ensure that the present value of RO is suitable to current 
purposes. 


You may use a general register specifier as the initial parameter in a run-time macro call. 
When you use a register other than RO, the contents of the specified register are moved to 
RO. The previous contents of RO are overwritten (and thus destroyed). 


The following statement reflects the use of a general register to specify the FDB address: 
FDAT$R RO,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by FCS as the address of the appropriate 
FDB. This method assumes that the address of the FDB has been previously loaded into RO 
through some overt action. Note, when using this method to specify the FDB address, that 
the immediate expression indicator (#) must not precede the register specifier (RO). 
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3. A null specification may be used as the initial parameter in a run-time macro call, as shown 
in the following statement: 


FDAT$R ,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by default as the address of the associated 
FDB. As shown previously, RO is assumed to contain the address of the desired FDB. 
Although the comma in this instance constitutes a valid specification, you are advised to 
employ methods 1 and 2 for consistency and clarity of purpose. 


These three methods of specifying the FDB address also apply to all the FCS file-processing 
macro calls described in Chapter 3. 


2.4 Global Versus Local Definitions for FDB Offsets 


Although the FDB offsets can be defined either locally or globally, the design of FCS does not 
require that you be concerned with the definition of FDB offsets locally. To some extent, this 
design consideration is based on the manner in which MACRO-11 handles symbols. 


Whenever a symbol appears in the source program, MACRO-11 assumes that it is a global 
symbol unless it is presently defined within the current assembly. Such a symbol must be 
defined further on in the program; otherwise, it will be treated by MACRO-11 as a default 
global reference, requiring that it be resolved by the Task Builder. 


Thus, the question of global versus local symbols may simply be a matter of the programmer's 
not defining the FDB offsets and bit values locally in coding the program. Such undefined 
symbols thus become global references, which are reduced to absolute definitions at task-build 
time. 


It should be noted that global symbols may be used as operands and macro-call parameters, or 
both, anywhere in the source program coding, as described in the following section. 


2.4.1 Specifying Global Symbols in the Source Code 


Throughout the descriptions of the assembly-time macros (see Sections 2.3.1.2 to 2.3.1.6), global 
symbols are specified as parameters in the macro calls. As noted earlier, such symbols are 
treated by MACRO-11 as default global references. 


For example, the global symbol FD.RAN may be specified as the initial parameter in the 
FDRC$A macro call (see Section 2.3.1.3). At task-build time, this parameter is reduced to an 
absolute symbol definition, causing a prescribed bit to be set in the record access byte (offset 
location F.RACC) of the FDB. 


Global symbols may also be used as operands in your task’s instructions to accomplish operations 
associated with FDB offset locations. For example, global offsets such as F.RACC, F.RSIZ, and 
F.RTYP may be specified as operands in the source coding. Assume, for example, that an 
FDBDF$ macro call (see Section 2.3.1.1) has been issued in the source program to allocate space 
for an FDB, as follows: 


FDBIN: FDBDF$ 
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The coding sequence shown in the following text may then appear in the source program, 
illustrating the use of the global offset F.RACC: 


MOV #FDBIN , RO 
MOVB #FD.RAN,F.RACC(RO) 


Note that the beginning address of the FDB is first moved into general register zero (RO). 
However, if the desired value already exists in RO as the result of previous action in the 
program, you need issue only the second MOV instruction (which appropriately references RO). 
As a consequence of this instruction, the value FD.RAN initializes FDB offset location F.RACC. 


The following statement is an equivalent instruction, which similarly initializes offset location 
F.RACC in the FDB with the value of FD.RAN: 


MOVB #FD RAN , FDBIN+F .RACC 


Global symbols may be used anywhere in the program in this manner to effect the dynamic 
storage of values within the FDB. 


2.4.2 Defining FDB Offsets and Bit Values Locally 


If you want your task to declare explicitly that all FDB offsets and bit values are to be defined 
locally, there are two macro calls in the source program you can invoke. The first of these, 
FDOF$L, causes the offsets for FDBs to be defined within your program. Similarly, bit values 
for all FDB parameters may be defined locally by invoking the FCSBT$ macro call. You can 
invoke these macro calls anywhere in your program. 


When issued, the FDOF$L and FCSBT$ macro calls define symbols in a manner roughly 
equivalent to the following: 


F.RTYP = xxxx 
F.RACC = xxxx 
F.RSIZ = xxxx 
Parameter 
XXXX 


Represents the value assigned to the corresponding symbol. 


In other words, the macros for defining FDB offsets and bit values locally do not generate 
any code. Their function is simply to create absolute symbol definitions within the program 
at assembly time. The symbols so defined, however, appear in the MACRO-11 symbol table, 
rather than in the source program listing. Such local symbol definitions are thereby made 
available to MACRO-11 during assembly, rather than forcing them to be resolved by the Task 
Builder. 


Whether the FDOF$L and FCSBT$ macros are invoked should not in any way affect the coding 
style or the manner in which the FDB offsets and bit values are used. 


Note, however, that if the FDOF$L macro is issued, the NBOF$L macro for the local definition 
of the filename block need not be issued (see Section 2.5.2). The FDOF$L macro defines all 
FDB offsets locally, including those for the filename block. 


If any of the previously named macros is to be issued in your program, it must first be listed 
as an argument in a .MCALL directive (see Section 2.2). 
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2.5 Creating File Specifications Within Your Program 


Certain information describing the file must be present in the FDB before the file can be opened. 
The file is located using a file specification that contains the following: 


e A device name and unit number. 


e A directory string consisting of a group number and a member number that specify the 
User File Directory (UFD) to be used for the file. The term “UFD” is synonymous with the 
term “file directory string,” which appears throughout this manual. 


e_ 6A file name. 
e A file type. 
e_ A file version number. 


A file specification describing the file to be processed is communicated to FCS through the 
following two data structures that you create: 


e The data-set descriptor. This tabular structure may be created and initialized manually 
through the use of .WORD directives. Section 2.5.1 describes this data structure in detail. 


© The default filename block. In contrast to the manually created data-set descriptor, the 
default filename block is created by issuing the NMBLK$ macro call. This macro call 
allocates a block of storage in your program at assembly time and initializes this structure 
with parameters supplied in the call. This structure is described in detail in Section 2.5.2. 


As noted in Section 2.3.1.5, the FDOP$A or the FDOP$R macro call is issued to initialize the 
EDB with the addresses of these data structures. These address values are supplied to FCS 
through the dspt and dfnb parameters of the selected macro call. FCS uses these addresses to 
access the fields of the data-set descriptor and the default filename block, or both, for the file 
specification required in opening a specified file. 


By convention, a required file specification is first sought by FCS in the data-set descriptor. 
Any nonnull data contained therein is translated from American Standard Code for Information 
Interchange (ASCII) to Radix-50 format and is stored in the appropriate offsets of the filename 
block. This area of the FDB then serves as the execution time repository for the information 
describing the file to be opened and processed. If the data-set descriptor does not contain the 
required information, FCS attempts to obtain the missing information from the default filename 
block. If neither of these structures contains the required information, an open failure occurs. 


Note, however, that the device name and the unit number need not be specified in either 
the data-set descriptor or the default filename block, because these values are defaulted to the 
device and unit assigned to the logical unit number (LUN) at task-build time if not explicitly 
specified. 

The FCS file-processing macro calls used in opening files are described in Chapter 3, beginning 
with the generalized OPEN$x macro call. 


For a detailed description of the format and content of the filename block, refer to Appendix B. 
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2.5.1 Data-Set Descriptor 


The data-set descriptor is often oriented toward the use of a fixed (built-in) file name in your 
program. A given application program, for example, may require access only to a limited and 
nonvariable number of files throughout its execution. By defining the names of these files 
at assembly time through the data-set descriptor mechanism, such a program, once initiated, 
executes to completion without requiring additional file specifications. 


This structure, a 6-word block of storage that you can create manually within your program by 
using .WORD directives, contains information describing a file that you intend to open during 
the course of program execution. In creating this structure, you can define any one or all of 
three possible string descriptors for a particular file, as follows: 


A 2-word descriptor for an ASCII device name string. You can allocate this data structure 
by using the following format: 


Word 1 


Word 2 


Contains the length (in bytes) of the ASCII device name string. 


This string consists of a 2-character alphabetic device name, followed by an 
optional octal unit number and an optional colon or a logical name. You can 
create these strings by issuing statements such as the following: 


DEVNM: .ASCII /DUO:/ 
DEVNM: .ASCII /TT1i0:/ 


Contains the address of the ASCII device name string. 


A 2-word descriptor for an ASCII file directory string. You can allocate this data structure 
by using the following format: 


Word 3 


Word 4 


Contains the length (in bytes) of the ASCII file directory string. 


This string consists of a group number and a member number, separated by a 
comma (,). The entire string is enclosed in brackets. For example, [200,200] is a 
directory string. You can create a directory string by issuing statements such as 
the following: 


DIRNM: .ASCII /[200,200]/ 
DIRNM: .ASCII /[40,100]/ 
If you want your task to specify an explicit file directory different from the 


UFD under which you are currently running, the data-set descriptor mechanism 
permits that flexibility. 


Contains the address of the ASCII file directory string. 


A 2-word descriptor for an ASCII filename string. You can allocate this data structure by 
using the following format: 


Word 5 


Contains the length (in bytes) of the ASCII filename string. 


This string consists of a file name up to 9 characters in length, an optional 
3-character file type designator, and an optional file version number. The file 
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name and file type must be separated by a period (.), and the file version number 
must be preceded by a semicolon. A filename string may be created as shown in 
the following statement: 


FILNM: .ASCII /PROG1.0BJ;7/ 


For Files-11, only the characters A to Z and 0 to 9 may be used in composing 
an ASCII filename string. An ANSI magnetic tape filename string may contain, 
in addition, the following special characters: 

SP17%&'()*+,-.f/:; <=> ? 

A name that contains any of these characters must be enclosed in quotation 
marks (””). If a quotation mark is part of the name, the string must contain 
two quotation marks. An ANSI filename string may be created as shown in the 
following example: 


FILNM: .ASCII /"PROG""2"" ;%&;";7/ 


The file name created in the previous example is as follows: 


PROG"2" ; 4&; 7 


Note 


The semicolon is a legal character in the name string. 
To delimit a version number, the semicolon must be 
outside the quoted string. 


Word 6 Contains the address of the ASCII filename string. 


A length specification of 0 in Word 1, 3, or 5 of the data-set descriptor indicates that the 
corresponding device name, directory, or filename string is not present in your program. For 
example, the following code creates a data-set descriptor containing only a 2-word ASCII 
filename string descriptor: 


FDBOUT: FDBDF$ ;CREATES FDB. 
FDAT$A R.VAR,FD.CR  ;INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRC$A_ ,RECBUF ,80. ; INITIALIZES RECORD-ACCESS SECTION. 


FDOP$A OUTLUN,OFDSPT ; INITIALIZES FILE-OPEN SECTION. 


OFDSPT: .WORD 0,0 ;NULL DEVICE-NAME DESCRIPTOR. 
-WORD 0,0 ;NULL DIRECTORY DESCRIPTOR. 
.WORD ONAMSZ,ONAM ;FILENAME DESCRIPTOR. 


ONAM: -ASCII /OQUTPUT.DAT/ ;DEFINES FILENAME STRING. 
ONAMSZ= . -ONAM ;DEFINES LENGTH OF FILENAME STRING. 
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Note first that an FDB labeled FDBOUT is created. Observe further that the FDOP$A macro call 
takes as its second parameter the symbol OFDSPT. This symbol represents the address value 
stored in FDB offset location F.DSPT. This value enables the .PARSE routine (see Chapter 4) to 
access the fields of the data-set descriptor in building the filename block. 


The symbol OFDSPT also appears in the label field of the first WORD directive, defining the 
address of the data-set descriptor for the .PARSE routine. The .WORD directives each allocate 
two words of storage for the device name descriptor, the file directory descriptor, and the file 
name descriptor, respectively. 


In the preceding example, however, note that the first two descriptor fields are filled with zeros, 
indicating null specifications. The last .WORD directive allocates two words that contain the 
size and the address of the filename string, respectively. The filename string itself is explicitly 
defined in the .ASCII directive that follows. 


Note that the statements defining the filename string need not be physically contiguous to the 
data-set descriptor. For each such ASCII string referenced in the data-set descriptor, however, 
corresponding statements must appear elsewhere in the source program to define the appropriate 
ASCII data string or data strings. 


A data-set descriptor for each of several files to be accessed by your program may be defined 
in this manner. 


2.5.2 Default Filename Block—NMBLK$ Macro 


As noted earlier, you may also define a default filename block in the program as a means of 
providing required file information to File Control Services (FCS). For this purpose, you can 
issue the NMBLK$ macro call in connection with each FDB for which a default filename block 
is to be defined. When this macro call is issued, space is allocated within your program for the 
default filename block, and the appropriate locations within this data structure are initialized 
according to the parameters supplied in the call. 


Note in the parameter descriptions in the following text that symbols of the form N.xxxx are 
used to represent the offset locations within the filename block. These symbols are differentiated 
from those that apply to the other sections of the FDB by the beginning character N. All versions 
of the generalized OPEN$x macro call (see Chapter 3) use these symbols to identify offsets in 
storing file information in the filename block. 


Format 
label: NMBLK$ fnam,ftyp,fver,dvnm,unit 


Parameters 


label 
Specifies a symbol, which you define, that names the default filename block and defines its 
address. This label is the symbolic value normally specified as the dfnb parameter when 
the FDOP$A or the FDOP$R macro call is issued. This causes FDB offset location F.DFNB 
to be initialized with the address of the default filename block. 
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fnam 
Specifies the default file name. This parameter may consist of up to nine ASCII characters. 
The character string is stored as 6 bytes in Radix-50 format, starting at offset location 
N.FNAM of the default filename block. 


ftyp 
Specifies the default file type. This parameter may consist of up to three ASCII characters. 
The character string is stored as 2 bytes in Radix-50 format in offset location N.FTYP of 
the default filename block. 


fver 
Specifies the default file version number (binary). When specified, this binary value identifies 
a particular version of a file. This value is stored in offset location N.FVER of the default 
filename block. 


dvnm 
Specifies the default name of the device upon which the volume containing the desired 
file is mounted. This parameter consists of two ASCII characters that are stored in offset 
location N.DVNM of the default filename block. 


unit 
Specifies a binary value identifying which unit (among several like units) is to be used in 
processing the file. If specified, this numeric value is stored in offset location N.UNIT of 
the default filename block. 


Only the alphanumeric characters A to Z and 0 to 9 may be used in composing the filename and 
file type strings discussed previously. Although the file version number and the unit number 
discussed previously are binary values, these numbers are normally represented in octal form 
when printed, when input by a command string, or when supplied through a data-set descriptor 
string. 


As evident from the preceding text, all the default information supplied in the NMBLK$ macro 
call is stored in the default filename block at offset locations that correspond to identical fields 
in the filename block within the FDB. This default information is moved into the corresponding 
offsets of the filename block when any version of the generalized OPEN$x macro call is issued 
under any of the following conditions: 


© All the file information required by FCS to open the file is not present in the data-set 
descriptor. Missing information is then sought in the default filename block by the .PARSE 
routine (see Chapter 4), which is invoked as a result of issuing any version of the generalized 
OPEN$x macro call. 


e A data-set descriptor has not been created in your program. 


* A data-set descriptor is present in your program, but the address of this structure has not 
been made available to FCS through any of the assembly-time or run-time macro calls that 
initialize FDB offset location F.DSPT. 
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The following code illustrates the general method of specifying the NMBLK$ macro call: 


FDBOUT: FDBDF$ ; ALLOCATES SPACE FOR AN FDB. 
FDAT$A R.VAR,FD.CR ; INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRC$A_ ,RECBUF,80. ; INITIALIZES RECORD-ACCESS SECTION. 
FDOP$A OUTLUN, ,OFNAM ; INITIALIZES FILE-OPEN SECTION. 

FDBIN: FDBDF$ ; ALLOCATES SPACE FOR AN FDB. 
FDRC$A_ ,RECBUF,80. ; INITIALIZES RECORD-ATTRIBUTE SECTION. 
FDOP$A INLUN,,IFNAM ; INITIALIZES FILE-OPEN SECTION. 

OFNAM: NMBLK$ OUTPUT,DAT ; ESTABLISHES FILE NAME AND FILE TYPE. 


IFNAM: NMBLK$ INPUT,DAT,,DT,1 ;ESTABLISHES FILE NAME, FILE TYPE, 
;DEVICE NAME, AND UNIT NUMBER. 


The first NMBLK$ macro call in the previous coding sequence creates a default filename block 
to establish default information for the FDB, named FDBOUT. The label OFNAM in this macro 
defines the beginning address of the default filename block allocated within your program. 
Note that this symbol is specified as the dfnb parameter in the FDOP$A macro call associated 
with this default filename block to initialize the file open section of the corresponding FDB. 
The accompanying parameters in the first NMBLK$ macro call define the file name and the file 
type, respectively, of the file to be opened; all remaining parameter fields in this call are null. 


The second NMBLK$ macro call accomplishes essentially the same operations in connection 
with the FDB, named FDBIN. Note in this macro call that the third parameter (the file version 
number) is null, as reflected by the extra comma. This null specification indicates that the latest 
version of the file is desired. All other parameter fields contain explicit declarations defining 
default information for the applicable FDB. 


You can define the offsets for a filename block locally in your program by issuing the following 
macro call: 


NBOF$L 


This macro call does not generate any code. Its function is merely to define the filename block 
offsets locally, presumably to conserve symbol table space at task-build time. The NBOF$L 
macro call need not be issued if the FDOF$L macro call has been invoked because the filename 
block offsets are defined locally as a result of issuing the FDOF$L macro call. 


If you want, you may initialize fields in the default filename block directly with appropriate 
values. You can do this by placing inline statements in the program. For example, a specific 
offset in the default filename block may be initialized through coding that is logically equivalent 
to the following coding: 


DFNB: NMBLK$ RSXLIB,OBJ 
NUTYP: .RAD50 /DAT/ 


MOV NUTYP , DFNB+N .FTYP 
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The symbol NUTYP in the MOV instruction represents the address of the newly defined 
Radix-50 file type DAT, which is to be moved into destination offset N.FTYP of the default 
filename block labeled DFNB. 


You can manually initialize any of the offsets within the default filename block in this manner 
to establish desired values or to override previously initialized values. 


Note 


The NMBLK$ macro cannot be used to create a file name containing non-Radix—50 characters 
or a file name that is not in the normal filenam.typ format. A program that uses the file name 
format permitted for ANSI magnetic tape must set up the file name in a data-set descriptor. 


2.5.3 Dynamic Processing of File Specifications 


If you want your task to make use of routines available from the system object li- 
brary ({1,1JSYSLIB.OLB) for processing command line input dynamically, consult Chapter 6. 
Chapter 6 describes the Get Command Line (GCML) routine and the Command String Interpreter 
(CSI) routine, both of which may be linked with your program to provide all the logical capa- 
bilities required in processing dynamic terminal input or indirect command file input. 


2.6 Optimizing File Access 


When certain information is present in the filename block beginning at the symbolic F.FNB 
of an File Descriptor Block (FDB), a file can be opened in a manner referred to throughout 
this manual as “opening a file by file ID.” This type of open requires a minimum of system 
overhead, resulting in a significant increase in the speed of preparing a file for access by your 
program. If files are frequently opened and closed during program execution, opening files by 
file ID accomplishes substantial savings in overall execution time. 


To open a file by file ID, the minimum information that must be present in the filename block 
of the associated FDB consists of the following: 


File identification field A 3-word field beginning at the filename block offset location 
N.FID that contains a file number in the first word and a 
file sequence number in the second word; the third word is 
reserved. The file identification field is maintained by the 
system and ordinarily need not be of concern to you. 


Device name field A 1-word field at the filename block offset location N.DVNM 
that contains the 2-character ASCII name of the device on 
which the volume containing the desired file is mounted. 


Unit number field A 1-word field at the filename block offset location N.UNIT 
that contains a binary value identifying the particular unit 
(among several like units) on which the volume containing 
the desired file is mounted. 


These three fields are written into the filename block in one of the following three ways: 


° By issuing any version of the generalized OPEN$x macro call for a file associated with the 
FDB in question 
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¢ By initializing the filename block manually by using the .PARSE routine and the .FIND 
routine (see Chapter 4) 


¢ By moving the necessary values into the filename block 


2.6.1 Initializing the Filename Block as a Function of OPENSx 


To understand how to effect the process of opening a file by file ID, note that the initial issuance 
of the generalized OPEN$x macro call (see Chapter 3) for a given file first invokes the .PARSE 
routine (see Chapter 4). The .PARSE routine is linked into your program, along with the code 
for OPEN$x. This routine first zeros the filename block and then fills it in with information 
taken from the data-set descriptor and the default filename block. 


Thus, issuing the generalized OPEN$x macro call invokes the .PARSE routine each time a file 
is opened. The .PARSE function, however, can be bypassed altogether in subsequent OPEN$x 
calls by saving and restoring the filename block before attempting to reopen that same file. 


This is made possible because of the logic of the OPEN$x macro call. Specifically, after the 
initial OPEN$x for a file has been completed, the necessary context for reopening that file exists 
within the filename block. Therefore, before closing that file, the entire filename block can be 
copied into your task’s memory space and later restored to the FDB at the desired point in 
program flow for use in reopening that same file. 


Your task can reopen files in this manner because FCS is sensitive to the presence of any 
nonzero value in the first word of the file identification field of the filename block. When your 
task invokes the OPEN$x function, FCS first examines offset location N.FID of the filename 
block. If the first word of this field contains a value other than 0, FCS logically assumes that the 
remaining context necessary for opening that file is present in the filename block, and therefore 
unconditionally opens that file by file ID. 


To ensure that an undesired value does not remain in the first word of the N.FID field from a 
previous OPEN$x or CLOSE$ sequence, the first word of this field is zeroed as the file is closed. 


In opening files by file ID, you need only ensure that manual saving and restoring of the 
filename block are accomplished with inline MOV instructions that are consistent with the 
desired sequence of processing files. This process should proceed as follows: 


1. Open the file in the usual manner by issuing the OPEN$x macro call. 


2. Save the filename block by copying it into your task’s memory space with appropriate MOV 
instructions. The filename block begins at offset location F.FNB in the FDB. 


The value of the symbol S.FNB is the size of the filename block in bytes, and the value 
of the symbol S.FNBW is the size of the filename block in words. If desired, the NBOF$L 
macro call (see Section 2.5.2) may be invoked in your program to define these symbols 
locally. These symbolic values may be used in appropriate MOV instructions to accomplish 
the saving and restoring of the filename block. Moreover, you must reserve sufficient space 
in the program for saving the filename block. 


3. At the end of current file operations, close the file in the usual manner by issuing the 
CLOSE$ macro call. 


4. When, in the normal flow of program logic, that same file is about to be reopened, restore 
the filename block to the FDB by reversing step 2. 
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5. Reopen the file by issuing any one of the macro calls available in FCS for opening an 
existing file. Because the first word of offset location N.FID of the filename block now 
contains a nonzero value, FCS unconditionally opens the file by file ID, regardless of the 
specific type of open macro call issued. 


Although you must save only the file identification, device name, and unit number fields of 
the filename block in anticipation of reopening a file by file ID, you are advised to save the 
entire filename block. The file name, file type, file version, and directory-ID fields, and so forth, 
may also be relevant. For example, an OPEN$x, save, CLOSE$, restore, OPEN$x, and DELET$ 
sequence would require saving and restoring the entire filename block. 


Though you may be logically finished with file processing and may want to delete the file, the 
delete operation will not work properly unless the entire filename block has been saved and 
restored. 


2.6.2 Manually Initializing the Filename Block 


In addition to saving and restoring the filename block in anticipation of reopening a file by file 
ID, you can also initialize the filename block manually. If you choose to do so, the .PARSE 
and .FIND routines (see Chapter 4) may be invoked at appropriate points to build the required 
fields of the filename block. After the PARSE and .FIND logic is completed, all the information 
required for opening the file exists within the filename block. When any one of the available 
FCS macro calls that open existing files is then issued, FCS unconditionally opens that file by 
file ID. 


Occasionally, instances arise that make such manual operations desirable, especially if your 
program is operating in an overlaid environment. In this case, it is highly desirable that the 
code for opening a file be broken into small segments in the interest of conserving memory 
space. Because the body of code for the OPEN$x and .PARSE functions is sizable, two other 
types of macro calls for opening files are provided for use with overlaid programs. The OFID$ 
and OFNB$ macro calls (see Chapter 3) are specifically designed for this purpose. 


The structure recommended for an overlaid environment is to have either the OFID$ or the 
OFNB$ code on one branch of the overlay and the .PARSE and .FIND code on another branch. 
Then, if you want your task to open a file by file ID, the PARSE and .FIND routines can be 
invoked at will to insert required information in the filename block before opening the file. 


The OFID$ macro call can be issued only in connection with an existing file. The OFNB$ macro 
call, on the other hand, may be used for opening either an existing file or for creating and 
opening a new file. In addition, the OFNB$ macro call requires only the manual invocation of 
the .PARSE routine to build the filename block before opening the file. 


If conservation of memory is an objective, and if your program will be opening both new and 
existing files, it is recommended that only the OFNB§ routine be included in one branch of the 
overlay; including the OFID$ routine would needlessly consume memory space. 


In all cases, however, it is important to note that all the macro calls for opening existing files 
are sensitive to the presence of any nonzero value in the first word (N.FID) of the filename 
block. If this field contains any value other than 0, the file is unconditionally opened by file 
ID. This does not imply, however, that only the file identification field (N.FID) is required to 
open the file in this manner. The device name field (N.DVNM) and the unit number field 
(N.UNIT) must also be appropriately initialized. The logic of the FCS macro calls for opening 
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existing files assumes that these other required fields are present in the filename block if the file 
identification field contains a nonzero value. 


Because many programs continually reuse FDBs, the CLOSE$ function (see Chapter 3) puts 
zeros in the file identification field (N.FID) of the filename block. This action prevents the field 
(which pertains to a previous operation) from being used mistakenly to open a file for a current 
operation. Thus, if your task later intends to open a file by file ID using information presently 
in the filename block, the entire filename block (not just N.FID) must be saved before closing 
the file. Then, at the appropriate point in program flow, the filename block may be restored to 
open the desired file by file ID. 


2.7 Initializing the File Storage Region 


2.7. 


The file storage region (FSR) is an area allocated in your program as a buffer pool to accommodate 
the program’s block buffer requirements in performing record I/O (GET$ and PUT$) operations. 
Although the FSR is not applicable to block I/O (READ$ and WRITE$) operations, you must 
issue the FSRSZ$ macro once in every program that uses FCS, regardless of the type of I/O to 
be performed. 


The macro calls associated with the initialization of the FSR are described next. 


1 FSRSZ$—Initialize FSR at Assembly Time 


The MACRO-11 programmer establishes the size of the FSR at assembly time by issuing an 
FSRSZ$ macro call. This macro call does not generate any executable code. It merely allocates 
space for a block-buffer pool in a program section named $$FSR1. The amount of space 
allocated depends on information provided by you, or defaulted, during the macro call. 


Note 


The FSRSZ$ macro allocates the FCS impure area that is pointed to by a fixed 
location in your task’s virtual memory. This pointer is not altered when overlays 
are loaded; therefore, the FSRSZ$ macro must be invoked in the root segment 
of a task. Unpredictable results may occur if the FSRSZ$ macro is invoked in 
more than one parallel overlay. 


Format 
FSRSZ$_fbufs,bufsiz,psect 


Parameters 
fbufs 
Specifies a numeric value that you establish as follows: 


¢ If no record I/O processing is to be done, fbufs equals 0. A value of 0 indicates that 
an unspecified number of files may be open simultaneously for block I/O processing. 
For example, if you intend to access three files for block I/O operations and no files for 
record I/O operations, the FSRSZ$ macro call takes 0 as an argument as follows: 


FSRSZ$ 0 


No other parameters need be specified unless the function of the psect parameter is 
required. 
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° If record I/O, using a single buffer for each file, is to be done, fbufs represents the 
maximum number of files that can be open simultaneously for record I/O processing. 
For example, you might want to access simultaneously three files for block I/O and two 
files for record I/O. You would specify the following FSRSZ$ macro call: 


FSRSZ$ 2 


Additional parameters, bufsiz and psect (described subsequently) could also be specified 
as required. 


° If record I/O with multibuffering is to be done, fbufs represents the maximum number 
of buffers ever in use simultaneously among all files open concurrently for record I/O. 
Assume, for example, that your program will simultaneously access four disk files for 
record I/O operations. Assume further that you want double buffering for three of 
the disk files and have, therefore, specified a multibuffer count of 2 in the FDBF$A 
macro calls (refer to Section 2.3.1.6) for the associated files. You would then issue the 
following FSRSZ$ macro call: 


FSRSZ$ 7 


This macro call indicates that a maximum of seven buffers will be in use simultaneously. 
This total is calculated as follows: one buffer for the single-buffered file and two buffers 
for each of the three double-buffered files. Additional parameters, bufsiz and psect 
(described next), could also be specified as required. 


bufsiz 
Specifies a numeric value defining the total block buffer pool space (in bytes) needed to 
support the maximum number of files that can be open simultaneously for record I/O. If 
this parameter is omitted, FCS obtains a total block buffer pool requirement by multiplying 
the value specified in the fbufs parameter with a default buffer size of 512 bytes. If, for 
example, a maximum of two single-buffered disk files will be open simultaneously for record 
1/O, either of the following FSRSZ$ macro calls could be issued: 


FSRSZ$ 2 
FSRSZ$ 2, 1024. 


If you want your task to explicitly specify block buffer pool requirements, the following 
formula must be applied: 


pufsiz=(bsizei*mbc1) [+(bsize2*mbc2) .. . +(bsizen*mbcn) ] 


bsize1,bsize2, ... ,bsizen 

Indicates the sizes, in bytes, of the buffers to support each file. The size of a buffer for 
a particular file depends on the device supporting the file if the standard block buffer size 
is used. Standard block sizes for devices are established at system generation time. The 
override block buffer size (ovbs) parameter can be used in the FDBF$x macro call to increase 
buffer size, as described in Section 2.3.1.6; these increases must be considered when you 
explicitly specify block buffer pool requirements. 


mbcl,mbce2, ... ,mben 
Indicates the multiple buffer counts (refer to Section 2.3.1.6) specified for the respective files. 
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The total value expressed by the bufsiz parameters must always represent the worst case 
buffer pool requirements among all combinations of simultaneously open record I/O files. 
The number of files (or buffers) representing the worst case is expressed as the first parameter 
of the macro call. 


psect 
Specifies the name of the program section (PSECT) to which control returns after FSRSZ$ 
completes processing. If no name is specified, control returns to the blank PSECT. 


2.7.2 FINIT$—tInitialize FSR at Run Time 


In addition to the FSRSZ$ macro call described in the preceding section, the FINIT$ macro call 
must also be issued in a MACRO-11 program to call initialization coding to set up the FSR. 


Format 
label: FINIT$ 


Parameter 


label 
Indicates an optional symbol, which you specify, that allows control to be transferred to 
this location during program execution. Other instructions in the program may reference 
this label, as in the case of a program that has been written so that it can be restarted. 


The FINIT$ macro call should be issued in the program’s initialization code. The first FCS 
call issued for opening a file performs the FSR initialization implicitly (if it has not already 
been accomplished through an explicit invocation of the FINIT$ macro call). However, it is 
necessary, in the case of a program that is written so that it can be restarted, to issue the FINIT$ 
macro call in the program’s initialization code, as shown in the next example. This requirement 
derives from the fact that such a program performs all its initialization at run time, rather than 
at assembly time. 


For example, a program that is not written so that it can be restarted might accomplish the 
initialization of the FSR implicitly through the following macro call: 


START: OPEN$R #FDBIN ; IMPLICITLY INITIALIZES THE FSR 
;AND OPENS THE FILE. 


In this case, although transparent to you, the OPEN$R macro call invokes the FINIT$ operation. 
The label START is the transfer address of the program. 


In contrast, a program that embodies the capability to be restarted must issue the FINIT$ macro 
call explicitly at program initialization as shown here: 


START: FINIT$ ;EXPLICITLY INITIALIZES THE FSR AND 
OPEN$R #FDBIN ;O0PENS THE FILE. 


In this case, the FINIT$ macro call cannot be invoked arbitrarily elsewhere in the program; it 
must be issued at program initialization. Doing so forces the reinitialization of the FSR, whether 
or not it has been done in a previous execution of the program through an OPEN$x macro call. 
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It is important to realize that calling any of the file control routines described in Chapter 4, 
such as .PARSE, first requires the initialization of the FSR. However, the FINIT$ operation must 
be performed only once each program execution. Note also that FORTRAN programs issue a 
FINIT$ macro call at the beginning of the program execution; therefore, MACRO—11 routines 
used with the FORTRAN Object Time System (OTS) must not issue a FINIT$ macro call. 


2.8 Increasing the Size of the File Storage Region 


Procedures for increasing the size of the FSR for either MACRO—11 or FORTRAN programs are 
presented in Sections 2.8.1 and 2.8.2. 


2.8.1 FSR Extension Procedures for MACRO-11 Programs 


Increase the size of the FSR for a MACRO-11 program by following either of the following 
procedures: 


* Modify the parameters in the FSRSZ$ macro call to redefine the buffer pool requirement of 
files open simultaneously for record I/O processing. Reassemble the program. 


¢ Use the EXTSCT (extend program section) command at task-build time to define the new 
size of the FSR. To invoke this option, specify the command in the following form: 


EXTSCT = $$FSR1:length 


Parameter 


SSFSRI1 
Specifies the symbolic name of the program section within the FSR that is reserved as 
the block buffer pool length. A numeric value defining the total required size of the 
buffer pool in bytes. 


The size of the FSR cannot be reduced at task-build time. 
In calculating the total length of the FSR, you can use either of the following formulas: 
¢ Length = (S.BFHD*fbufs)+bufsiz 
¢ Length = fbufs*(S.BFHD+512;0) 


Length Argument 


$.BFHD 
Specifies a symbol that defines the number of bytes required for each block buffer 
header. You can define this symbol locally in your program by issuing the following 
macro call: 


BDOFF$ DEFS$L 


fbufs 
Specifies a numeric value representing either the maximum number of files open 
simultaneously for record I/O (when single buffering only is used) or the maximum 
number of buffers ever in use simultaneously among all files open concurrently for 
record I/O (when multibuffering is used). Refer also to the description of this parameter 
in the FSRSZ$ macro call in Section 2.7.1. 
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bufsiz 
Specifies a numeric value defining the total block buffer pool space (in bytes) needed to 
support the maximum number of files that can be open simultaneously for record I/O. 
Refer to the description of this parameter in the FSRSZ$ macro call in Section 2.7.1. 


51210 
Specifies the standard default buffer size. 


The EXTSCT option is described in detail in the RSX-11M-PLUS and Micro/RSX Task Builder 
Manual. 


2.8.2 FSR Extension Procedures for FORTRAN Programs 


For a FORTRAN program, if an explicit ACTFIL option is not issued to the Task Builder, an 
ACTFIL statement with a default value of 4 is generated during task build. You may extend 
the size of the FSR at task-build time by issuing the following command: 


ACTFIL = files 


Parameter 


files 


Specifies a decimal value defining the maximum number of files that may be open 
simultaneously for record I/O processing. 


This command, like the EXTSCT command described previously, causes program section $$FSR1 
to be extended by an amount sufficient to accommodate the number of active files anticipated 
for simultaneous use by the program. 


The size of the FSR for a FORTRAN program can also be decreased at task-build time. As noted 
previously, the default value for the ACTFIL command is 4. Thus, if 0, 1, 2, or 3 is specified 
as the “files” parameter, the size of $$FSR1 (the FSR block buffer pool) is reduced accordingly. 


The ACTFIL option is described in detail in the RSX-11M-PLUS and Micro/RSX Task Builder 
Manual. 


2.9 Coordinating I/O Operations 


Your programs perform all 1/O operations by issuing GET$ or PUT$ and READ$ or WRITE$ 
macro calls. (See Chapter 3 for a complete discussion of these file-processing macro calls.) 
These calls do not access the physical devices in the system directly. Rather, when any one of 
these calls is issued, an I/O-related system macro called Queue I/O (QIO$, QIO$C, or QIO$S) 
is invoked as the interface between the File Control Services (FCS) file-processing routines at 
the user level and the system I/O drivers at the device level. Device drivers are included for 
all the standard I/O devices supported by RSX-11 systems. Although transparent to your task, 
the QUEUE I/O directive is used for all FCS file access operations. 


When invoked, the QIO$ macro instructs the system to place an I/O request for the associated 
physical device unit into a queue of priority-ordered requests for that unit. This request is placed 
according to the priority of the issuing task. As required system resources become available, 
the requested I/O transfer takes place. 
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As implied previously, the following two separate and distinct processes are involved in 
accomplishing a specified I/O transfer: 


1. The successful queuing of the GET$ or PUT$ or READ$ or WRITE$ I/O request 
2. The successful completion of the requested data transfer operation 


These processes, both of which yield success/failure indications that may be tested by your 
program, must be performed successfully for the specified I/O operation to be completed. It 
is important to note that FCS totally synchronizes record I/O operations for you, even in the 
case of multibuffered operations. In the case of block I/O operations, the flexibility of FCS 
allows you to synchronize all block I/O activities, thus enabling you to satisfy logical processing 
dependencies within the program. 


2.9.1 Event Flags 


I/O operations proceed concurrently with other system activity. After an I/O request has been 
queued, the system does not force an implied wait for the issuing task until the requested 
operation is completed. Rather, the operation proceeds in parallel with the execution of the 
issuing task, and it is the task’s responsibility to synchronize the execution of I/O requests. 
Tasks use event flags in synchronizing these activities. The system executes operations that 
manipulate, test, and wait for these indicators of internal task activity. 


The completion of an I/O transfer, for example, is recognized by the system as a significant 
event. If you have specified a particular event flag to be used by the task in coordinating 
1/O-completion processing, that event flag is set, causing the system to evaluate the eligibility 
of other tasks to run. Any event flag from 1 to 32,9 may be defined for local use by the 
task. If you have not specified an event flag, FCS uses event flag 3219 by default to signal the 
completion of I/O transfers. 


Specific FDB-initialization and I/O-initiating macro calls in FCS enable you to specify event 
flags, if desired, that are unique to a particular task and that are set and reset only as a result 
of that task’s operation. 


For record I/O operations, such an event flag may be defined through the efn parameter of the 
FDBF$A or the FDBF$R macro call (see Section 2.3.1.6 or 2.3.2, respectively). 


For block I/O operations, an event flag may be declared through the bkef parameter of the 
FDBK$A or the FDBK$R macro call (see Section 2.3.1.4 or 2.3.2, respectively); alternatively, a 
block event flag may be declared through the corresponding parameter of the I/O-initiating 
READ$ or WRITE$ macro call (see Chapter 3). 


In both record and block I/O operations, the event flag is cleared when the I/O request is 
queued and is set when the I/O operation is completed. In the case of record I/O operations, 
only FCS manipulates the event flag. Additionally, the event flag’s state is transparent to your 
task, which must not issue a WAITFOR system directive predicated on the event flag used for 
coordinating record I/O operations. A record I/O operation, for example, may not even involve 
an I/O transfer; rather, it may only involve the blocking or deblocking of a record within the file 
storage region (FSR) block buffer. On the other hand, the event flag defined for synchronizing 
block I/O operations is totally under your control. 
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Also, a code indicating the success or failure of the QIO$ macro request resulting from the 
READ$ or WRITE$ macro call is returned to the Directive Status Word (DSW). If desired, 
symbolic location DSW may be tested to determine the status of the I/O request. The 
success/failure codes for the QIO$ macros are listed in the RSX-11M-PLUS and Micro/RSX I/O 
Drivers Reference Manual. 


Event flag directives are described in the RSX-11M-PLUS and Micro/RSX Executive Reference 
Manual. The relationship of event flags to specific devices is described in the RSX-11M-PLUS 
and Micro/RSX I/O Drivers Reference Manual. 


2.9.2 |/O Status Block 


Because of the comparative complexity of block I/O operations, an optional parameter is 
provided in the FDBK$A and the FDBK$R macro calls, as well as in the READ$ and WRITE$ 
macro calls, that enables the system to return status information to your task for block I/O 
operations. The I/O status block (IOSB) is not applicable to record I/O (GET$ or PUT$) 
operations. 


This optional parameter, called the IOSB address, is made available to FCS through any of the 
macro calls identified previously. When this parameter is supplied, the system returns status 
information to a 2-word block reserved in your program. Although the IOSB is used principally 
as a QIO$ macro housekeeping mechanism for containing certain device-dependent information, 
this area also contains information of particular interest to you. 


Specifically, the second word of the IOSB is filled in with the number of bytes transferred 
during a READ$ or WRITE$ operation. When you are performing READ$ operations, it is 
good practice to use the value returned to the second word of the IOSB as the number of 
bytes actually read, rather than to assume that the requested number of bytes was transferred. 
Employing this technique allows the program to properly read virtual blocks of varying length 
from a device such as a magnetic tape unit, provided that the requested byte count is at least 
as large as the largest virtual block. For WRITE$ operations, the specified number of bytes is 
always transferred; otherwise, an error condition exists. 


Also, the low-order byte of the first word of the IOSB contains a code that reflects the final 
status of the READ$ or WRITES operation. The codes returned to this byte may be tested to 
determine the status of any given block I/O transfer. The binary values of these status codes 
always have the following significance: 


Code Value Meaning 

+ (plus sign) I/O transfer completed. 

0 I/O transfer still pending. 
- (minus sign) I/O error condition exists. 


The format of the IOSB and the error codes returned to the low-order byte of its first word are 
described in detail in the RSX-11M-PLUS and Micro/RSX I/O Drivers Reference Manual. 
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If the address of the IOSB is not made available to FCS (and hence to the QIO$ macro) through 
any of the macro calls noted previously, no status information is returned to the IOSB. In this 
case, the fact that an error condition may have occurred during a READ$ or WRITE$ operation 
is simply lost. Thus, supplying the address of the IOSB to the associated File Descriptor Block 
(FDB) is highly desirable and makes normal error reporting easier. 


An IOSB may be defined in your task at assembly time through any storage directive logically 
equivalent to the following: 


IOSTAT: .BLKW 2 


IOSTAT is a symbol, which you define, naming the IOSB and defining its address. This symbolic 
value is specified as the bkst parameter in the FDBK$A or the FDBK$R macro call to initialize 
FDB offset location F.BKST; it may also be specified as the corresponding parameter in the 
READ$ or the WRITE$ macro call. Initializing this cell in the FDB is an integral part of issuing 
the desired I/O request. 


2.9.3 AST Service Routine 


An asynchronous system trap (AST) is a software-generated interrupt that causes the sequence 
of instructions currently being executed to be interrupted and control to be transferred to another 
instruction sequence elsewhere in the program. If desired, you may specify the address of an 
AST service routine that is to be entered upon completion of a block I/O transfer. Because an 
AST is a trap action, it constitutes an indication of block I/O completion. 


The address of an AST service routine may be specified as an optional parameter (bkdn) in the 
FDBK$A or the FDBK$R macro call (see Section 2.3.1.4 or 2.3.2, respectively); this parameter 
may also be specified in the READ$ or the WRITE$ macro call, initializing the FDB at the time 
the I/O request is issued (see Chapter 3). 


Usually, an AST address is specified to enable a running task to be interrupted to execute special 
code upon completion of a block I/O request. If the address of an AST service routine is not 
specified, the transfer of control does not occur, and normal task execution continues. 


The main purpose of an AST service routine is to inform your task that a block I/O operation 
has been completed, thus enabling the program to continue immediately with some other 
desired (and perhaps logically dependent) operation (for example, another I/O transfer). 


If an AST service routine is not provided by you, some other mechanism, such as event flags 
or the IOSB, must be used as a means of determining block I/O completion. In the absence of 
such a routine, for example, you may test the low-order byte of the first word in the IOSB to 
determine if the block I/O transfer has been completed. A WAIT$ macro call (see Chapter 3) 
may also be issued in connection with a READ$ or WRITES operation to suspend task execution 
until a specified event flag is set to indicate the completion of block I/O. 


Implementing an AST service routine in your program is application dependent and must 
be coded specifically to meet your task’s particular I/O-processing requirements. A detailed 
discussion of ASTs is beyond the scope of this document. Refer to the RSX-11M-PLUS and 
Micro/RSX Executive Reference Manual for discussions of trap-associated system directives. 


Caution 


Do not execute any FCS routines while in an AST service routine. FCS maintains 
an impure data area that it uses as a Directive Parameter Block (DPB) and as 
a scratch area for directives. An AST could interrupt an FCS operation that is 


2-42 Preparing for I/O 


altering this impure area. Executing an FCS routine in AST state could alter the 
impure area and cause unpredictable results when task execution resumes. 


2.9.4 Block Locking 


Block locking selectively controls access to blocks within a file while that file is being read from 
or written to by one or more users. Block locking is a system generation option that can be 
used from FCS or RMS-11 or by issuing QIO$ macros. 


You can enable block locking only when the file is opened. Once block locking is enabled, you 
can establish “locks,” which are structures allocated from system dynamic storage that control 
access to specific blocks in the file. 


When your task reads or writes a block, the Executive creates a lock that subsequently restricts 
other users from writing to or reading from that block. When your task has a file open on 
a logical unit number (LUN) with block locking enabled and locks are created, your locks do 
not restrict your task from reading or writing blocks if you use the same LUN. Locks may be 
selectively eliminated by issuing a QIO$ macro with the IO.ULK (unlock) function code. You 
can only eliminate those locks that you have created. When your task closes the file, all your 
locks on that file are released to system dynamic storage. 


Block locking operates in the following ways when using FCS: 
1. Opens the file. 


To enable block locking when opening a file from FCS, you must change two fields in the 
FDB. The value FA.SHR in byte F.FACC must be set to allow shared write access to the 
file. Additionally, the values FA.LKL, FA.EXL, and FA.ENB must be set in word F.ACTL. 
Setting FA.SHR causes FCS to clear AC.LCK in the DPB. For example: 


FDOP$R #FDB,,,,#FA.SHR,#FA.LKL!FA.EXL!FA.ENB 
OPEN$R RO,,,,,,,, ERRSUB ;OPEN SHARED FOR READ WITH LOCKS 


2. Writes or reads blocks. 


A one-block read or write operation locks a block for exclusive access. A write or read 
operation of more than one block similarly locks all blocks operated on in this QIO$ macro. 
A file open for block mode may invoke READ$ and WRITE$ macros in the usual manner. 


Note that, in general, FCS operates as follows on sequential read access: 
a. OPENSR positions the file to record 1. 

b. GET$ returns record 1 and positions the file to record 2. 

c. GET$ returns record 2 and positions the file to record 3. 

d. GET$ returns record 3 and positions the file to record 4. 

Be aware that successive GET$ macros scan across the file sequentially. 


However, if you have files open for record mode operations, the following special 
considerations may exist: 


* A number of tasks are updating records in a single file. 


° One of these tasks is reading records sequentially. 
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For example, if the GET$ macro for record 2 in the task that reads blocks sequentially 
fails because record 2 is contained in a block previously locked by another task, FCS loses 
its position in the file. The next GET$ macro yields undefined results; it obtains neither 
record 2 nor record 3. 


After this kind of error occurs, FCS must re-position its pointer to the records in the file. 
This can happen in one of the following ways: 


¢ Operating in random mode on fixed-length records, FCS re-positions its record pointer 
to the first record for each GET$ or PUTS operation. 


¢ FCS re-positions the FCS pointer in a file of variable-length records by calling the FCS 
.POINT routine. You can re-position the pointer either to a location noted by a previous 
.MARK call or to the beginning of the file. 


* FCS closes and reopens the file to re-position the pointer to the beginning. 
3. Unlocks blocks. 


To unlock blocks without closing the file, you must execute a QIO$ macro with the function 
code IO.ULK. You can use IO.ULK to unlock one block, a series of blocks, or all the blocks 
in an open file. 


To unlock one or more blocks in a series, specify the block count in device-dependent 
parameter Word 2, specify the high 8 bits of the starting virtual block number (VBN) in the 
low byte of parameter Word 4, and specify the low 16 bits of the starting VBN in parameter 
Word 5. For example, to unlock previously locked VBNs 5, 6, and 7, use the following 


code: 

MOV #3,R0 ;UNLOCK 3 BLOCKS 
MOV #5,R1 ;STARTING AT VBN 5 
Qrowss #1I0.ULK,#MYLUN,#1, ,#IOSB, ,<,RO,,,R1> 


To unlock all blocks you have locked on this LUN, issue the QIO$ macro with no parameters 
beyond the device-independent part of the DPB, as follows: 


QIOWw$S #I0.ULK,#MYLUN, #1, ,#IOSB ;UNLOCK ALL BLOCKS 
Also, you can use FCS to execute the QIO$ macros for you by calling the .XQIO routine. 


To use the .XQIO routine to unlock all blocks that you have locked on this LUN and file, 
call .XQIO with no option parameters, that is, with R2=0 as follows: 


MOV #FDB,RO ;GET FDB ADDRESS 

MOV #10 .ULK,R1 ;UNLOCK BLOCK FUNCTION 

CLR R2 ;UNLOCK ALL BLOCKS 

CALL -XQIO ;EXECUTE QI0 

BCS ERROUT ;IF CS ERROR IS IN F.ERR(RO) 


To use .XQIO to unlock one or more blocks in a series, you must set up a 5-word param- 
eter block. Specify the count of blocks in Word 2, specify the high 8 bits of the starting 
VBN in the low byte of parameter Word 4, and specify the low 16 bits of the starting VBN in 


2-44 Preparing for I/O 


parameter Word 5. For example, to unlock the previously locked VBNs 5, 6, and 7, use the 
following code: 


PRMBK: .WORD 0 ;PARAMETER BLOCK FOR UNLOCK QIO 
-WORD 0 ;COUNT OF BLOCKS TO UNLOCK 
.WORD 0 ; 

.WORD 0 ;HIGH 8 BITS OF START VBN 
-WORD 0 ;LOW 16 BITS OF START VBN 
MOV #FDB,RO ;GET FDB ADDRESS 

MOV #I0.ULK,R1 ;UNLOCK BLOCK FUNCTION 

MOV #5 ,R2 ;FIVE PARAMETERS 

MOV #PRMBK,R3  ;ADDRESS OF PARAMETER BLOCK 
MOV #3 ,2(R3) ;UNLOCK 3 BLOCKS 

MOV #5,8. (R3) ;STARTING AT VBN 5 

CALL .XQIO ;EXECUTE QIO 

BCS ERROUT ;IF CS ERROR IS IN F.ERR(RO) 


4. Closes the file. 


Closing the file in the ordinary manner will release all blocks that have been established 
on that file for the specific task and LUN. 


2.9.5 Error Codes Related to Shared Files and Block Locking 


Error codes relating to file sharing and block locking may be returned in the following 
circumstances. 


Error Codes 


1. 


Opening the file 
The following error codes may occur when you attempt to open the file: 
IE.WAC, 


Explanation: Indicates that you have requested that other users be denied write access (no 
FCS FA.SHR or AC.LCK=1), but someone else has already opened the file to write to it. 


User Action: Do not attempt to open the file until all others writing to the file have closed 
it. 


IE.LCK, 
Explanation: Indicates that one of the following conditions is true: 


* You want to write to the file and have allowed shared write access (set FCS FA.SHR 
or AC.LCK=0), but someone else has already opened the file, denying others write 
access. 


User Action: Do not attempt to open the file until all accessors without shared write access 
have closed the file. 


¢ You want to write to the file and have allowed shared write access (set FCS FA.SHR 
or AC.LCK=0) without enabling block locking but someone else has already opened 
the file with block locking enabled. 


User Action: Open the file with block locking enabled. 
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e F11ACP cannot perform a directory operation because the directory is locked or 
being written to. 


User Action: The solution depends on what you anticipate as normal activity on your system. 
If it is legitimate for a task to access a directory, then consider attempting the operation 
again. 
IE.ULK, 


Explanation: Indicates that the Executive does not support block locking. This error can only 
be returned on an RSX-11M-PLUS system that has been generated without block locking 
support. 


User Action: Open the file without enabling block locking. 
2. Writing or reading blocks 


The following error codes may occur when you attempt to write or read blocks: 


IE.ULK, 


Explanation: Returned by the Executive when any read or write error occurs that relates to 
block locking. It generally means that another task has locked the block. 


User Action: The solution depends on the application. Wait and retry the operation or report 
the error and stop processing. 


3. Unlocking blocks 


The following error codes may occur when you attempt to unlock blocks: 


IE.IFC, 
Explanation: Returned when the Executive does not support block locking. 


User Action: Do not attempt to unlock blocks on a system that does not support block 
locking. 


IE.LCK, 


Explanation: Returned upon the occurrence of any other error. For example, IE.LCK is 
returned if another task has locked the blocks. 


User Action: Unlock only those blocks that you have previously locked for that file. 
4. Closing the file. 


No block locking error can occur when closing a file. 
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Chapter 3 
File-Processing Macros 


You can manipulate files through a set of file-processing macro calls. The assembler invokes and 
expands these macros at assembly time and the operating system executes the resulting code 
at run time. This chapter describes these run-time macro calls, which allow you to manipulate 
files and to perform the following I/O operations. Table 3-1 provides a brief description of 
each macro. 


Table 3-1: File-Processing Macro Calls 


Macro 


Call Function 
eee 
OPEN$ Opens and prepares a file for processing. 


OPNS$ Opens and prepares a file for processing and allows shared access to that file 
(depending on the mode of access.) 

OPNT$ Creates and opens a temporary file for processing. 

OFID$ Opens an existing file by using file identification information in the filename block. 

OFNB$ Opens a file by using file name information in the filename block. 

CLOSE$ Terminates file processing in an orderly manner. 

GET$ Reads logical data records from a file. 

GET$R Reads fixed-length records from a file in random mode. 

GET$S Reads records from a file in sequential mode. 

PUT$ Writes logical data records to a file. 

PUT$R Writes fixed-length records to a file in random mode. 

PUT$S Writes records to a file in sequential mode. 


READ$ Reads virtual data blocks from a file. 


File-Processing Macros 3-1 


Table 3-1 (Cont.): File-Processing Macro Calls 


Macro 
Call Function 


a 


WRITES Writes virtual data blocks to a file. 
WAITS Suspends program execution until a requested block I/O operation is completed. 


DELET$ Removes a named file from the associated volume directory and deallocates the 
space occupied by the file. 


et 


Most of the parameters associated with the file-processing macro calls supply information to the 
File Descriptor Block (FDB). Such parameters cause MOV or MOVB instructions to be generated 
in the object code, which results in the initialization of specific locations within the FDB. 


The final parameter in all file-processing macros is the symbolic address of an optional, user- 
defined error-handling routine. This routine is entered upon detection of an error condition 
during the file-processing operation. When this optional parameter is specified, the following 
code is generated: 


Code for macro 


BCC +6 ;TESTS CARRY BIT IN PROCESSOR STATUS WORD. 
CALL ERRLOC ; INITIATES ERROR-HANDLING ROUTINE 
;AT "ERRLOC" ADDRESS. 


If the operation is completed successfully, the Carry bit in the Processor Status Word (PSW) 
is not set, and FDB offset location F.ERR contains a positive value. The BCC instruction then 
results in a branch around the CALL instruction and normal program execution continues. 


However, if an error condition is detected during the execution of the file-processing routine, 
the Carry bit in the PSW is set, FDB offset location F.ERR contains a negative value (indicating 
an error condition), and the branch around the CALL instruction does not occur. Instead, the 
CALL instruction is executed, loading the program counter (PC) with the symbolic address 
(ERRLOC) of the error-handling routine and initiating its execution. 


If this optional parameter is not specified, the error-processing routine is not called, and you 
must explicitly test the Carry bit in the PSW to ascertain the status of the requested operation. 


Note that executing the File Control Services (FCS) file-processing routines causes all your task’s 
general registers, except RO, to be saved. FCS uses RO by convention to contain the address of 
the FDB associated with the file being processed. 
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3.1 OPEN$x—Generalized Open Macro 


Before any file can be processed by your task or system program, it must first be opened. 
An alphabetic suffix accompanying the macro name indicates to FCS the action you intend to 
perform on a file. For example, you might issue a generalized macro. 

Format 


OPEN$x 


Parameter 


xX 


Represents any one of the following alphabetic suffixes, each of which denotes a specific 
type of file processing: 


R Read an existing file. 

WwW Write (create) a new file. 

M Modify an existing file without changing its length. 

U Update an existing file and extend its length, if necessary. 
A Append (add) data to the end of an existing file. 


Note 
You can issue the generalized OPEN$x macro without an alphabetic suffix. In 
this case, the action to be performed on the file is indicated to FCS through 
an additional parameter in the macro. This value, called the file access (facc) 
parameter, causes offset location F.FACC in the associated FDB to be initialized. 
Section 3.7 describes this macro in detail. 


Depending on the alphabetic suffix supplied in the OPEN$x macro call, certain other types of 
operations may or may not be allowed, as follows: 


* If R is specified (for reading an existing file), that file cannot also be written; that is, a PUT$ 
or WRITES operation cannot be performed on that file. 


° If M or U is specified (for modifying or updating an existing file), that file can be both read 
and written; that is, concurrent GET$ and PUT$ or READ$ and WRITE$ operations can be 
performed on that file. 


* IfM is specified (for modifying an existing file), that file cannot be extended. 


* If W or A is specified (for creating a new file or for appending data to an existing file), that 
file can be read, written, or extended. 


The program that issues the OPEN$x macro must have appropriate access privileges for the 
specified action. Table 3-2 summarizes the access privileges for the various forms of the 
OPEN$x macro. This table also shows where the next record or block will be read or written 
in the file after it is opened. 
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Table 3-2: File Access Privileges Resulting from OPENSx Macro 


Macro Access Privileges Position of File After OPEN$x 

OPEN$R Read First record of existing file 

OPEN$W _ Read, write, extend First record of new file 

OPEN$M _ Read, write First record of existing file 

OPEN$U Read, write, extend First record of existing file 

OPEN$A Read, write, extend End of existing file (For special PUT$R considerations, 


see Section 3.13.) 


oo eS SS SS 


When your task issues any form of the OPEN$x macro, FCS first fills in the filename block with 
file name information retrieved from the data-set descriptor (see Chapter 2). FCS gains access 
to this data structure through the address value stored in FDB offset location F.DSPT. 


If any required data has been omitted from the data-set descriptor, FCS attempts to obtain 
the missing information from the default filename block. This data structure, which may also 
contain file name information specified in your task, is created in the program by issuing the 
NMBLK$ macro (see Chapter 2). FCS gains access to this structure through the address value 
stored in FDB offset location F.DFNB. 


The address values in offset locations F.DSPT and F.DFNB can be supplied to FCS through 
the FDOP$A macro, the FDOP$R macro call, or the OPEN$x macro. FCS requires access to 
the data-set descriptor or the default filename block in retrieving file name information used in 
opening files. 


If a new file is to be created, the OPEN$W macro is issued. FCS then performs the following 
operations: 


1. Creates a new file and obtains file identification information for the file. FCS maintains the 
file identification information in offset location N.FID of the filename block. The filename 
block in the FDB begins at the FDB offset location F.FNB. 


2. Initializes the file attribute section of the file header block. The file header block is a file 
system structure maintained on the volume containing the file. Each file on a volume has 
an associated file header block that describes the attributes of that file. FCS obtains attribute 
information for a new file from the FDB associated with the file. The format and content of 
a file header block are presented in detail in Appendix C. 


3. Places an entry for the file in the User File Directory (UED). If, however, an entry for a file 
having the same name, type, and version number already exists in the UFD, the old file is 
deleted. If your task explicitly issues a particular type of macro that specifies that the file 
not be superseded, the old file is not deleted and an error code is returned. This type of 
OPEN$ operation is described in Section 3.7. 


4. Associates the assigned logical unit number (LUN) with the file to be created. 


Allocates a buffer for the file from the file storage region (FSR) block buffer pool if record 
I/O (GET$ or PUTS) operations are processing the file. 
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3.1. 


If an existing file is to be opened, any one of the following macros may be issued: OPEN$R, 
OPEN$M, OPEN$U, or OPENG$A. FCS then performs the following operations: 


1. If file identification information is not present in the filename block, FCS constructs the 
filename block from information taken from the data-set descriptor and the default filename 
block, or both. FCS then searches the UFD by file name to obtain the required file 
identification information. When found, this information is stored in the filename block, 
beginning at offset location N.FID. 


2. Associates the assigned LUN with the file. 


3. Reads the file header block and initializes the file attribute section of the FDB associated 
with the file being opened. 


4. Allocates a buffer for the file from the FSR block buffer pool if record I/O (GET$ or PUT$) 
operations are processing the file. 


Note 


As described in Chapter 2, you allocate buffers through the FSRSZ$ macro. The 
number of buffers allocated is dependent upon the number of files that you 
intend to open simultaneously for record I/O operations. 


If your task uses block I/O operations, FDB offset location F.RACC must be initialized with the 
FD.RWM parameter by the FDRC$A, the FDRC$R, or the generalized OPEN$x macro. This 
parameter inhibits the allocation of a buffer when the file is opened. 


1 Format of Generalized OPENSx Macro 


The OPEN$x macro takes the general form shown next. 


Format 
OPEN$x_ fdb,lun,dspt,racc,urba,urbs,err 


Parameters 


x 


Represents the alphabetic suffix specified as part of the macro name, which indicates the 
desired type of operation to be performed on the file. The possible values for this parameter 
are: R, W, M, U, A, or no value at all (see Section 3.1). 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


lun 
Specifies the LUN associated with the desired file. This parameter identifies the device on 
which the volume containing the desired file is mounted. Normally, the LUN associated 
with the file is specified through the corresponding parameter of the FDOP$A or the 
FDOP$R macro. If so specified, the lun parameter need not be present in the OPEN$x 
macro. Each FDB must have a unique LUN. 
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dspt 
Specifies the symbolic address of the data-set descriptor. Normally, this address value is 
specified through the corresponding parameter of the FDOP$A or the FDOP$R macro. If 
so specified, this parameter need not be present in the OPEN$x macro. 


This parameter specifies the address of the manually created data-set descriptor (see 
Chapter 2). If the Command String Interpreter (CSI) interprets command lines dynamically, 
this parameter specifies the address of the data-set descriptor within the CSI control block 
(see offset location C.DSDS in Chapter 6). 


race 
Specifies the record access byte. One or more symbolic values may be specified in this field 
to initialize the record access byte (F.RACC) in the associated FDB. You can specify any 
combination of the following parameters by separating them with exclamation points: 


FD.RWM_ Requests that block I/O (READ$ or WRITES) operations are to process the file. 
If you do not specify this parameter, FCS assumes by default that record 1/O 
(GET$ or PUT$) operations are to process the file. 


FD.RAN _ Requests random access to the file for record I/O (GET$ or PUT$) operations. 
The file is opened and the first record is pointed to. With this parameter, a 
PUT$ operation in the file, without exception, does not truncate the file. If 
this parameter is not specified, FCS uses sequential access by default. Refer to 
Chapter 1 for a description of random access mode. 


FD.PLC Requests locate mode (see Chapter 1) for record I/O (GET$ or PUT$) operations. 
If this parameter is not specified, FCS uses move mode (see Chapter 1) by default. 


FD.INS Requests that a PUT$ operation in sequential mode in the body of a file shall 
not truncate the file. This parameter prevents the logical end of the file from 
being reset to a point just beyond the inserted record. If this parameter is not 
specified, a PUT$ operation in sequential mode truncates the file to a point just 
beyond the inserted record, but no deallocation of file blocks occurs. 


Specifying this parameter allows a data record in the body of the file to be overwritten. 
Care must be exercised, however, to ensure that the record being written is the same length 
as that of the record being replaced. 


If the record access byte in the FDB has already been initialized through the corresponding 
parameters of the FDRC$A or the FDRC$R macro, the racc parameters need not be present 
in the OPEN$x macro. 


urba 
Specifies the symbolic address of your task’s record buffer. This parameter initializes FDB 
offset location F.URBD+2. 


If your task’s record buffer address has already been supplied to the FDB through the 
corresponding parameter of the FDRC$A or the FDRC$R macro, this parameter need not 
be present in the OPEN$x macro. 


urbs 
Specifies a numeric value that defines the size of your task’s record buffer (in bytes). This 
parameter initializes FDB offset location F.URBD. 
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If the size of your task’s record buffer has already been supplied to the FDB through the 
corresponding parameter of the FORC$A or the FDRC$R macro, this parameter need not 
be present in the OPEN$x macro. 


err 
Specifies the symbolic address of an optional, user-coded error-handling routine. 


Specific FDB requirements for record I/O operations (GET$ and PUT$ macros) are detailed in 
Sections 3.9.2 and 3.12.2. 


The examples listed at the end of this section show sample uses of the OPEN$x macro. 


Note 


You can use RO only to pass the FDB address parameter. Any other use of RO when you issue 
the OPEN$A macro will fail. 


Examples 
OPEN$M RO,#INLUN, ,#FD.RAN!FD.PLC 


Opens and modifies an existing file. 


Note in this macro that the FDB address is assumed to be present in RO. The third parameter, 
that is, the data-set descriptor pointer, is not specified; this null specification (indicated by the 
extra comma) assumes that FDB offset location F.DSPT (if required) has already been initialized. 
The last parameter, consisting of two values separated by an exclamation point, establishes 
random access and locate modes for GET$ or PUT$ operations. 


OPENSU RO,#INLUN,, ,#RECBUF , #80. 
Updates an existing file. 


This macro also assumes that the FDB address is in RO. Note also that the dspt and racc 
parameter fields are null, based on the premise that the data-set descriptor pointer (F.DSPT) 
has been provided previously to the FDB and that the record access byte (F.RACC) has also 
been previously initialized. Finally, the last two parameters establish the address and the size, 
respectively, of your task’s record buffer. 


OPEN$A #0UTFDB 
Shows a macro that might be issued to allow data to be appended to the end of a file. 


This macro specifies the address of an FDB as the only parameter. In this case, it is assumed that 
all other parameters required by FCS in opening and operating on the file have been previously 
supplied to the FDB through the appropriate assembly-time or run-time macro. 


Note in all three preceding examples that the error parameter is not specified, requiring that 
you explicitly test the Carry bit in the PSW to ascertain the success of the specified operation. 
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3.1.2 FDB Requirements for Generalized OPENS$x Macro 


The information required for opening a file may be supplied to the File Descriptor Block (FDB) 
through the following macros: 


e The assembly-time macros described in Chapter 2 

¢ The NMBLK$ macro described in Chapter 2 

e The run-time macros described in Chapter 2 

¢ The various macros described in this chapter for opening files 


The use of any particular combination of macros to define and initialize the FDB is a matter of 
choice, as indicated previously. Of far greater significance is the fact that certain information 
must be present in the FDB before you can open the associated file. In this regard, the following 
rules apply for creating and opening new files, for opening existing files, and for specifying 
desired file options: 


1. To create a new file 


If a new file is to be created through the OPEN$W macro, the following information must 
first be supplied to the FDB. You can specify this information through the FDAT$A macro 
or the FDAT$R macro (see Chapter 2): 


a. The record type must be established for record I/O operations. 


The record type cannot be supplied to the FDB through any of the various macros used 
to create or open files (for example, OPEN$W, OPEN$R, and so forth). Furthermore, 
this information is not required when opening an existing file because FCS obtains such 
information from the first 14 bytes of your task’s file attribute section of the file header 
block (see Appendix C). 


To establish the record type, you must initialize byte offset location F.RTYP with the 
following symbolic values: 


R.FIX Requests that fixed-length records are to be written into the file. 
R.VAR Requests that variable-length records are to be written into the file. 
R.SEQ Requests that sequenced records are to be written into the file. 

b. The desired record attributes must be specified for record I/O operations. 


The record attributes cannot be supplied to the FDB through any of the various 
macros used to create or open files (for example, OPEN$W, OPENSR, and so forth). 
Furthermore, the record attributes are not required when opening an existing file because 
FCS obtains such information from the first 14 bytes of your task’s file-attribute section 
of the file header block (see Appendix C). 
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The record attributes are defined by initializing byte offset location F.LRATT with the 
appropriate value or values, as follows: 


FD.FTN Requests that the first byte of each record contain a FORTRAN carriage-control 
character. 


FD.CR Requests that a line-feed (<LF> ) character precede each record and that 
a carriage-return (<CR> ) character follow the record when that record is 
output to a device requiring carriage control information (for example, to a 
terminal). The <LF> and <CR> characters are not actually embedded 
within the record. Their presence is merely implied through the file attribute 
FD.CR. 


FD.BLK Requests that records be prevented from crossing block boundaries. 


FD.PRN Requests that the record be preceded by a word containing carriage-control 
information. Files with this attribute must also be sequenced files; that is, files 
with the bit R.SEQ set in the byte F.RTYP in the FDB. For more information 
about FD.PRN as a record attribute, see Chapter 2. 


If fixed-length records are to be written to the file, you must specify the record size (in 
bytes) for record 1/O operations to appropriately initialize FDB offset location F.RSIZ. 


The record size cannot be supplied to the FDB through any of the various macros used 
to create and open files, (for example, OPEN$W, OPEN$R, and so forth). Furthermore, 
the record size is not required when opening an existing file, because FCS obtains such 
information from the first 14 bytes of your task’s file-attribute section of the file header 
block (see Appendix C). 


2. To open either a new file or an existing file 


Regardless of whether the file being opened is yet to be created or already exists, the 
following information must be present in the FDB before that file can be opened: 


a. 


The record access byte must be initialized for record or block I/O operations. The 
symbolic values following may be specified in the FDRC$A macro (see Chapter 2), the 
FDRC$R macro call (see Chapter 2), or the generalized OPEN$x macro to initialize FDB 
offset location F.RACC: 


FD.RWM Requests that READ$ or WRITE$ (block I/O) operations process the file. If 
this parameter is not specified, GET$ or PUT$ (record I/O) operations result 
by default. 


FD.RAN _ Requests that random access mode (GET$ or PUT$ record 1/O) process the 
file. The file is opened and the first record pointed to. If this parameter is 
not specified, sequential access mode results by default. Refer to Chapter 1 
for a description of random access mode. 


FD.PLC Requests that locate mode (GET$ or PUT$ record I/O) process the file. If 
this parameter is not specified, move mode results by default. 


FD.INS Requests that a PUT$ operation in sequential mode in the body of a file shall 
not truncate the file. If this parameter is not specified, a PUT$ operation 
truncates the file. In this case, the logical end of the file is reset to a point 
just beyond the inserted record, but no deallocation of file blocks occurs. 
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b. Your task’s record buffer descriptors (that is, the urba and urbs parameters) must be 
specified for record I/O operations. To accomplish this, the FDRC$A, the FDRC$R, 
or the generalized OPEN$x macro may be used. The selected macro call defines the 
address and the size of the area reserved in the program for use as a buffer during 
record I/O operations. The urba and urbs parameters initialize FDB offset locations 
F,URBD+2 and F.URBD, respectively. 


FDB requirements specific to GET$ and PUT$ operations in move and locate mode are 
presented in detail in Sections 3.9.2 and 3.12.2, respectively, 


c. You must specify the logical unit number (LUN) to initialize FDB offset location F.LUN. 
Initialization of this cell can be accomplished with the lun parameter of the FDOP$A, 
the FDOP$R, or the generalized OPEN$x macro. Each FDB must have a unique LUN. 


d. If file identification information is not already present in the FDB, either the data-set 
descriptor pointer (F.DSPT) or the default filename block address (F.DFNB) must be 
specified to enable File Control Services (FCS) to obtain required file name information 
for use in opening the file. These address values may be specified in either the FDOP$A 
macro (see Chapter 2) or the FDOP$R macro (see Chapter 2). The generalized OPEN$x 
macro (see Section 3.1) may also be used to specify the data-set descriptor pointer. 


e. If desired, an event flag number for synchronizing record I/O operations must be 
specified to initialize FDB offset location F.EFN. This optional parameter may be specified 
in either the FDBF$A macro (see Chapter 2) or the FDBF$R macro (see Chapter 2). If 
not specified, FCS uses event flag number 3219 by default to synchronize all record I/O 
activity. 


3. To specify desired file options 


If certain options are desired for a given file, they must be specified before that file is 
opened. Because this information is needed only in opening the file, it is zeroed when the 
file is closed, thus ensuring that the FDB is properly reinitialized for subsequent use. The 
options that may be specified for a given file are as follows: 


a. The override block size (ovbs parameter) must be specified in either the FDBF$A or 
the FDBF$R macro to initialize FDB offset location F.OVBS. This parameter need be 
specified only if the standard default block size in effect for the associated device is to 
be overridden or if the big-buffering or multibuffering versions of FCS are in use. The 
override block size is specified to improve I/O system performance with record I/O 
and with record-oriented devices (such as line printers) and sequential devices (such as 
magnetic tape units). (See Chapter 2.) 


b. The multiple buffer count (mbct parameter) must be specified in either the FDBF$A or 
the FDBF$R macro to initialize FDB offset location F.MBCT. If multibuffered record I/O 
operations are to be used, this parameter must be greater than 1, and it must agree with 
the desired number of buffers to be used. This parameter is neither overlaid nor zeroed 
when the file is closed. 


If the multiple buffer count is not established as described previously, multibuffered 
operations can still be invoked by changing the default buffer count in the file storage 
region (FSR). A default buffer count of 1 is stored in symbolic location .MBFCT of 
$$FSR2. This default value can be altered to reflect the number of buffers intended for 


3-10 File-Processing Macros 


use during record I/O operations. The procedure for modifying this cell in $$FSR2 is 
described in Chapter 2. 


In addition, if your task uses multibuffering, you must specify the appropriate control 
flag as the mbfg parameter in either the FDBF$A or the FDBF$R macro to appropriately 
initialize FDB offset location F.MBFG. Either of two symbolic values may be specified 
for this purpose, as follows: 


FD.RAH Requests that read-ahead operations are to process the file. 
FD.WBH Requests that write-behind operations are to process the file. 


Offset location F.MBFG need be initialized only if the standard default buffering 
assumptions are inappropriate. When a file is opened for reading (OPEN$R), read- 
ahead operations are assumed by default; for all other forms of OPEN$x, write-behind 
operations are assumed. It may be useful, for example, to override the write-behind 
default assumption for a file opened through the OPEN$M or the OPEN$U macro when 
that file is being used basically for sequential read operations, but scattered updating is 
also being performed. 


c. To allocate required file space at the time a file is created, the cntg parameter must 
be specified in either the FDAT$A or the FDAT$R macro. This parameter initializes 
FDB offset location F.CNTG. A positive value specifies results in the allocation of a 
contiguous file having the specified number of blocks; a negative value, on the other 
hand, results in the allocation of a noncontiguous file having the specified number of 
blocks. 


d. The address of the 5-word statistics block in your program must be moved manually 
into FDB offset location F.STBK. This address value specifies an area in your task to 
which FCS returns certain statistical information about a file when it is opened. If this 
parameter is not specified, no return of such information occurs. 


The format and content of the statistics block are presented in Appendix D. You can 
define such an area in a program with coding logically equivalent to the following: 


STBLK: .BLKW 5 
Offset location F.STBK may then be initialized manually, as follows: 
MOV #STBLK , FDBADR+F . STBK 


STBLK is the symbolic address of the statistics block, which you define. The destination 
operand of this instruction defines the appropriate offset location within the desired 
FDB. 


3.2 OPNS$x—Open File for Shared Access 


The OPNS$x macro opens a file for shared access. This macro has the same format: that 
is, it takes the same alphabetic suffixes and run-time parameters as the generalized OPEN$x 


macro. The shared access conditions that result from the use of this macro are summarized in _ 


Chapter 1. 
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3.3 OPNTSW—Create and Open Temporary File 


The OPNT$W macro creates and opens a temporary file for some special purpose of limited 
duration. If a temporary file is to be used only once, it is best created through the OPNT$D 
macro described in Section 3.4 


The OPNT$W macro creates a file but does not enter a file name for that file into any associated 
User File Directory (UFD). 


In using the OPNT$W macro, you bear the responsibility for marking the temporary file 
for deletion, as described in the procedure in the following text. Then, after all operations 
associated with that file are completed, closing the file results in its deallocation. All space 
formerly occupied by the file is then returned for reallocation to the pool of available storage 
on the volume. 


Although the OPNT$W macro takes the same format and parameters as those of the generalized 
OPEN$x macro, the former executes faster because no directory entries are made for a temporary 
file. 

Creating a temporary file is usually done when a program requires a file only for the duration 


of its execution (for example, for use as a work file). The general sequence of operations in 
such instances proceeds as follows: 


1. Open a temporary file by issuing the OPNT$W macro. Perform any desired operations 
on that file. If the file is to be used only for a single OPNT$W/CLOSE$ sequence, go to 
step 6; otherwise, continue with step 2. 


2. Before closing the file for processing, save the filename block in the associated FDB. The 
general procedure for saving (and restoring) the filename block is discussed in Chapter 2. 


3. Close the file by issuing the CLOSE$ macro (see Section 3.8). Continue other processing in 
the program, as desired. 


4. In anticipation of reopening the temporary file, restore the filename block to the FDB by 
reversing step 2. 


5. Reopen the file by issuing any of the FCS macros that open existing files. Resume operations 
on the file; repeat the save, CLOSE$, restore, open sequence any desired number of times. 


6. Before closing the file for the last time, call the .MRKDL routine, to mark the file for deletion 
as follows: 


CALL . MRKDL 
The .MRKDL routine is described in Chapter 4. 
7. Close the file by issuing the CLOSE$ macro. 


If the filename block is not saved, the file identification field therein is destroyed because this 
field is reset to 0 when the file is closed. 


Thus, if you do not save the filename block before closing a temporary file, a “lost” file results 
because no directory entry is made for a temporary file. Therefore, the usual procedure of 
listing the volume’s directory is inapplicable. The only way such a file can be recovered is to 
use the File Structure Verification Utility program (VFY) to search the volume’s index file. The 
VFY program has the capability to compare the files listed in all the directories on the volume 
with those listed in the index file. If a file appears in the index file, but not in a directory, VFY 
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identifies that file for you. This program is described in detail in the RSX-11M-PLUS Utilities 
Manual. 


3.4 OPNT$D—Create and Open Temporary File and Mark for 
Deletion 


The OPNT$D macro creates and opens a temporary file. This macro is a convenient way to 
perform steps 1 and 6 shown in Section 3.3. A file marked for deletion cannot be opened by 
another program. Furthermore, when the file is closed, it is deleted from the volume, which 
returns its space to the pool of available storage on the volume for reallocation. 


The presumption in issuing the OPNT$D macro is that the created file is to be used only once. 
This is a desirable way to open a temporary file because the file will be deleted even if the 
program terminates abnormally without closing the file. 


The following OPNT$D macro takes the same format and parameters as those of the generalized 
OPEN$x macro (as described in Section 3.1.1): 


OPNT$D fdb,lun,dspt,racc,urba,urbs,err 


Note 


If the OPNT$D macro is used for a temporary file containing sensitive information, it is 
recommended that you zero the file before closing it, or reformat the disk to destroy the 
sensitive information. (Although a temporary file is deleted after use, the information physically 
remains on the volume until written over with another file, and it could be analyzed by 
unauthorized users.) 


3.5 OFIDSx—Open File by File ID 


You issue the OFID$x macro to open an existing file that uses information stored in the file 
identification field (offset location N.FID) of the filename block in the FDB (not in your default 
filename block). Thus, when you issue this macro, it invokes an FCS routine that opens a file 
only by file ID (see Chapter 2). The following OFID$x macro, which has the same format and 
takes the same parameters as those of the generalized OPEN$x macro (see Section 3.1), is for 
use with overlaid programs: 


OFID$x fdb,lun,dspt,racc,urba,urbs,err 
In describing the functions of the OFID$x macro, either one of the following two assumptions 
may apply: 


¢ The necessary context for opening the file has been saved from a previous OPEN$x operation 
and has been restored to the filename block in anticipation of opening that file by file ID. 
Saving and restoring the filename block are discussed in detail in Chapter 2. 


e The desired file is to be opened for the first time. In that case, the necessary context for 
opening the file must first be stored in the filename block before the OFID$ macro can be 
issued. 
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In most cases, the latter assumption applies, requiring that the following procedures be 
performed: 


1. Call the .PARSE routine (see Chapter 4). This routine takes information from a specified 
data-set descriptor or default filename block, or both, and initializes and fills in the specified 
filename block. 


2. Call the .FIND routine (see Chapter 4). This routine locates an appropriate directory entry 
for the file (by file name) and stores the file identification information found there in the 
6-byte file identification field of the filename block, starting at offset location N.FID. (As a 
result of steps 1 and 2, the necessary context then exists in the associated filename block 
for opening the file by file ID.) 


3. Issue the OFID$x macro. 


The advantage of using the .PARSE and .FIND routines with the OFID$x macro is that you can 
overlay the program, placing .PARSE and .FIND on one branch, and the code for OFID$x on 
another branch. This overlay structure reduces the program’s overall memory requirements. 


Unlike the other FCS macros for opening files, the OFID$x macro requires a nonzero value in 
the first word of the file identification field (N.FID) to work properly. When this field contains 
a nonzero value, FCS assumes that the remaining context necessary for opening that file is 
present and, accordingly, opens the file by file ID. 


Opening an existing file by file ID for write access is a special case. Because you are intending 
to rewrite the existing file, the following occur: 


¢ Any initial allocation (F.CNTG) is ignored. 
e File access byte (F.FACC) value NA.NSP (do not supersede file) is ignored. 


e File access byte (F.FACC) value FA.CRE (create new file) is set even though the file is being 
rewritten rather than created. 


¢ This operation may not be performed on American National Standards Institute (ANSI) 
magnetic tape. The data in the file header labels is not changed when the file is written. 
See Chapter 5 for information on positioning file on tape to rewrite a file in a particular 
position. 


The OFID$W macro is equivalent to the OFID$U macro. Invoking either OFID$W or OFID$U 
opens an existing file by file ID number for update and extension. 


3.6 OFNB$x—Open File by Filename Block 


The OFNB$x macro either opens an existing file or creates and opens a new file by using file 
name information in the filename block. Like the OFID$x macro previously described, the 
OFNB$x call is for use with overlaid programs. However, the OFNB$x macro differs in two 
important respects: it can be issued to create a new file, and it can be issued to open a file by 
filename block. 


The following OFNB$x call has the same format and takes the same parameters as those of the 
generalized OPEN$x macro (as described in Section 3.1.1): 


OFNB$x fdb,lun,dspt,racc,urba,urbs,err 
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The OFNB$x macro also uses the same suffixes that are available to the OPEN$x macro: 
OFNB$R, OFNB$W, OFNB$M, OFNB$U, OFNB$A. The suffixes have the same meaning as 
they do for OPEN$x (see Table 3-2). 


The same assumptions outlined for OFID$x apply to the functions of the OFNB$x macro; 
namely, that the filename block has been saved and restored in anticipation of issuing the 
OFNB$x macro, or that the file is being opened for the first time. Because the procedures 
for saving and restoring the filename block are detailed in Chapter 2, the following discussion 
assumes that the desired file is being opened for the first time. In this case, the filename block 
in the FDB must be initialized. 


To open a file by filename block, the following information must be present in the filename 
block of the associated FDB: 


° The file name (offset location N.FNAM) 
° The file type or extension (offset location N.FTYP) 
e The file version number (offset location N.FVER) 
° The directory ID (offset location N.DID) 
° The device name (offset location N.DVNM) 
¢ The unit number (offset location N.UNIT) 
In providing the information to the filename block, you can use either of two general procedures, 
which are described in Sections 3.6.1 and 3.6.2. 
3.6.1 Data-Set Descriptor or Default Filename Block 


If the data-set descriptor contains all the required information listed previously, perform the 
following procedure: 


1. Call the .PARSE routine (see Chapter 4). This routine takes information from a specified 
data-set descriptor and default filename block, and the routine fills in the appropriate offsets 
of a specified filename block. 


2. Issue the OFNB$x macro. 


3.6.2 Default Filename Block Only 


If a default filename block is to be used in providing the required information to FCS, perform 
the following procedure: 


1. Issue the NMBLK$ macro (see Chapter 2) to create and initialize a default filename block. 
With the exception of the directory ID, this structure provides all the requisite information 
to FCS. 


2. Call either of the following routines to provide the directory ID: 


~ Call the .GTDIR routine (see Chapter 4) to retrieve the directory ID from the specified 
data-set descriptor and to store the directory ID in the default filename block. 


- Call the .GTDID routine (see Chapter 4) to retrieve the default User Identification Code 
(UIC) from $$FSR2 and to store the directory ID in the default filename block. 
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3. Move the entire default filename block manually into the filename block associated with 
the file being opened. 


4, Issue the OFNB$x macro. 


Note that the coding for OFNB$x operations normally resides in an overlay apart from that 
containing the other File Control Services (FCS) routines identified previously. 


Issuing the OFNB$x macro is usually done under the premise that the filename block contains 
the requisite information, as described previously. However, if the file identification field (offset 
location N.FID) in the filename block contains a nonzero value when the call to OFNB$x is 
issued, the file is unconditionally opened by file ID. 


If you expect to open both new and existing files, and memory conservation is an objective, 
the OFNB$x macro is most suitable for opening such files. The OFID$x coding should not be 
included in the same overlay with OFNB$x, because OFID$x overlaps the function of OFNB$x 
and, therefore, needlessly consumes memory space. 


3.7 OPENS—Generalized Open for Specifying File Access 


Usually, when you want to create a file, the file name and the file type are specified, and FCS 
is allowed to assign the next higher file version number. However, if the OPEN$W macro is 
issued for a file having an explicit file name, file type, and file version number, and a file of that 
description already exists in the specified User File Directory (UFD), the old file is superseded. 


By issuing the OPEN$ macro without an alphabetic suffix, and by specifying two additional 
parameters, you can inhibit the superseding of a file when a duplicate file specification is 
encountered in the UFD. Rather than deleting the old version of the file, an error indication 
(IE.DUP) is returned to offset location F.ERR of the applicable File Descriptor Block (FDB). 


All parameters of this macro are identical to those specified for the generalized OPEN$x macro 
(see Section 3.1), with the exception of the facc parameter and the dfnb parameter. These 
additional parameters are described in this section. 

Format 


OPEN$__ fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err 


Parameters 


facc 
Specifies any one or an appropriate combination of the following symbolic values, which 
indicate how the specified file is to be accessed: 


FO.RD Requests that an existing file is to be opened for reading only. 
FO.WRT Requests that a new file is to be created and opened for writing. 
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FO.APD Requests that an existing file is to be opened and appended. 
FO.MFY Requests that an existing file is to be opened and modified. 
FO.UPD Requests that an existing file is to be opened, updated, and, if necessary, extended. 


FA.NSP Requests, in combination with FO.WRT, that the old file having the same file 
specification is not to be superseded by the new file. 


FA.TMP Requests, in combination with FO.WRT, that the file is to be a temporary file. 
FA.SHR Requests that the file is to be opened for shared access. 


dfnb 


Specifies the symbolic address of the default filename block. This parameter is the same as 
that described in connection with the FDOP$A/FDOP$R macro. 


The previously described parameters initialize FDB offset locations F.KACC and F.DFNB with 
the appropriate value. 


Any logically consistent combination of the previously described file access symbols is 
permissible. The particular combination required to create and write a new file without 
superseding an existing file follows: 


OPEN$ #0UTFDB,#F0.WRT!FA.NSP 
The following macro creates a temporary file for shared access: 


OPEN$ #OUTFDB,#F0O.WRT!FA.TMP!FA.SHR 


Note 


You can use RO only to pass the FDB address parameter. Any other use of RO when you issue 
the OPEN$ macro will fail. 


3.8 CLOSES—Close Specified File 


When the processing of a file is completed, you must close the file by issuing the CLOSE$ 
macro. The CLOSE$ operation performs the following housekeeping functions: 


1. Waits for all 1/O operations in progress for the file to be completed (multibuffered record 
1/O only) 


2. Ensures that the FSR block buffer, which contains data for an output file, is completely 
written if it is partially filled (record I/O only) 


By default, truncates the file being closed 
Deaccesses the file 
Releases the FSR block buffer or buffers allocated for the file (record I/O only) 


Pe a 


Prepares the FDB for subsequent use by clearing appropriate FDB offset locations 
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7. Calls an optional user-coded and user-specified error-handling routine if an error condition 
is detected during the CLOSE$ operation 


Note that I/O does occur in items 1 and 2. Therefore, your program should include error 
processing for CLOSE$ calls as it would for calls to PUTS. 


If you issue a CLOSE$ when a file is already closed, a success status code results. It is not an 
error if you close a file that is already closed. The format of the CLOSE$ macro is shown next. 


Format 
CLOSE$ __ fdb,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


err 
Specifies the symbolic address of a user-coded, optional error-handling routine. 


Examples 
CLOSE$ #FDBIN,CLSERR 


Shows an explicit declaration for the relevant FDB, and the symbolic address of a user-coded 
error-handling routine to be entered if the CLOSE$ operation is not completed successfully. 


CLOSE$ ,CLSERR 
CLOSE$ RO 


Assume that RO currently contains the address of the appropriate FDB. 


3.9 GET$S—Read Logical Record 


The GET$ macro reads logical records from a file. After a GET$ operation, the next record buffer 
descriptors in the FDB always identify the record just read; that is, offset location F.NRBD+2 
contains the address of the record just read, and offset location F.NRBD contains the size of 
that record (in bytes). This is true of GET$ operations in both move and locate mode. 


In move mode, a GET$ operation moves a record to your task’s record buffer (as defined by the 
current contents of F.URBD+2 and F.URBD), and the address and size of that record are then 
returned to the next record buffer descriptors in the FDB (F.NRBD+2 and F.NRBD). 


In locate mode, if the entire record resides within the file storage region (FSR) block buffer, then 
the address and the size of the record just read are returned to the next record buffer descriptors 
(F.NRBD+2 and F.NRBD). If, on the other hand, the entire record does not reside within the 
FSR block buffer, then that record is moved piecemeal into your task’s record buffer, and the 
address of your task’s record buffer and the size of the record are returned to offset locations 
F.NRBD+2 and F.NRBD, respectively. 


After returning from a GET$ operation in locate mode, regardless of whether moving the record 
was necessary, F.NRBD+2 always contains the address of the record just read, and F.NRBD 
always contains the size of that record. 
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If the record read was a sequenced record, the sequence number is stored in F. SEQN regardless 
of whether the GET$ was in move mode or locate mode. 


GET$ operations are fully synchronous; that is, record I/O operations are completed before 
control is returned to your program. 


Specific FDB requirements for GET$ operations are presented in Section 3.9.2. 


3.9.1 Format of GETS Macro 


The format of the GET$ macro is shown next. 


Format 
GET$_  fdb,urba,urbs,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


urba 
Specifies the symbolic address of your task’s record buffer that is to be used for record I/O 


operations in move or locate mode. When specified, this parameter initializes FDB offset 
location F.URBD+2. 


urbs 
Specifies a numeric value that defines the size (in bytes) of your task’s record buffer. This 
parameter determines the largest record that can be placed in your task’s record buffer in 
move or locate mode. When specified, this parameter initializes offset location F.URBD in 
the associated FDB. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


If neither the urba nor the urbs parameter is specified in the GET$ macro, FCS assumes that 
these requisite values have been supplied previously through the FDRC$A, the FDRC$§R, or the 
generalized OPEN$x macro. Any resulting nonzero values in offset locations F.URBD+2 and 
F.URBD are used as the address and the length, respectively, of your task’s record buffer. 


If either of the following conditions occurs during record I/O operations, FCS returns an error 
indication (IE.RBG) to offset location F.ERR of the FDB, which indicates an illegal record size: 


*¢ In move mode, the record size exceeds the limit specified in offset location F.\URBD. 


¢ In locate mode, the record size exceeds the limit specified in offset location F.URBD, and 
the record must be moved because it crosses block boundaries. 


In both move and locate mode, only data up to the amount specified in F.URBD is placed in 
your task’s buffer. The next GET$ begins reading at the beginning of the next record. 


The statements listed in the examples at the end of this section show how the GET$ macro 
may be used in a program. 
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Note 


You can use RO only to pass the FDB address. Any other use of RO when you issue the GET$ 
macro will fail. 


Examples 
GET$ RO, , ,ERROR 


Assumes the address of the desired FDB is present in RO. Note that the next two parameters, 
that is, your task’s record buffer address (urba) and your task’s record buffer size (urbs), are 
null. In this case, FCS assumes that the appropriate values for FDB offset locations F.URBD+2 
and F.URBD, respectively, have been specified previously in the FDRC$A, the FDRC$R, or the 
generalized OPEN$x macro. The final parameter in the string is the symbolic address of a 
user-coded error-handling routine. 


GET$ , #RECBUF , #25. , ERROR 


Assumes that RO contains the address of the desired FDB. Explicit parameters then define the 
address and the size, respectively, of your task’s record buffer and an error handler, which you 
coded. 


GETS #INFDB 
Shows a GET$ macro in which only the address of the FDB is specified. 


3.9.2 The FDB Relevant to GETS Operations 


The following sections summarize the essential aspects of GET$ operations in move and locate 
mode with respect to the associated FDB. 


The following text focuses on whether your task’s record buffer is required under certain 
conditions. In this regard, you should recall that your task’s record buffer descriptors, that 
is, the urba and the urbs parameters, may be specified in the FDRC$A, the FDRC$R, or the 
generalized OPEN$x macro, as well as the I/O-initiating GET$ macro. These parameters must 
be present in the GET$ macro (to appropriately initialize the FDB) only if they were not 
previously supplied through other available means. 


If operating in random access mode, the number of the record to be read is maintained by FCS 
in offset locations F. RCNM and F.RCNM+2 of the associated FDB. FCS increments this value 
after each GET$ or GET$R operation to point to the next record in the FSR block buffer. 


Thus, unless your task alters the values in locations F.RCNM and F.RCNM4+#2 before each 
issuance of the GET$ or GET$R macro call, the next record in sequence is read. Your specified 
record buffer size (that is, the urbs parameter) always determines the largest record that can be 
read during a GET$ operation. 


3-20 File-Processing Macros 


3.9.2.1 GETS Operations in Move Mode 


With respect to GET$ operations in move mode (refer to Chapter 1 for information on move 
mode), the following generalization applies. If records are always moved to the same record 
buffer in your task, the urba and urbs parameters need be specified only in the initial GET$ 
macro. Alternatively, these values may be specified beforehand through any available means 
identified previously, for initializing your task’s record buffer descriptor cells in the FDB. In any 
case, offset locations F.URBD+2 and F.URBD remain appropriately initialized for all subsequent 
GET$ operations in move mode that involve the same record buffer in your task. 


3.9.2.2 GET$ Operations in Locate Mode 


In performing GET$ operations in locate mode (refer to Chapter 1 for information on locate 
mode), you should take the following information into account: 


Note 
In the following text, reference is made to the FSR block buffer. By default, the 
block size that FCS uses is equivalent to the buffer size of the device on which 
the file is opened. If big buffering is enabled (that is, an ovbs parameter value 
is specified in the FDBF$x macro, as described in Chapter 2) the FSR block 
buffer will be more than one block long. As a result, it may not be necessary to 
move a record even though it crosses block boundaries because both blocks are 
currently within the FSR block buffer space. Thus, moves are only necessary 
when the record crosses a buffer boundary, which is not necessarily the same 
as a block boundary in a big-buffered file. 


* If fixed-length records are to be processed, and if they fit evenly within the FSR block 
buffer, your task’s record buffer descriptors need not be present in the associated FDB. 


e If fixed-length records that do not fit evenly within the FSR block buffer are to be processed, 
or if variable-length records are to be processed, your task’s record buffer descriptors need 
not be present in the FDB, provided that the file being processed exhibits the attribute of 
records not being allowed to cross block boundaries (FD.BLK). 


The property of records not crossing block boundaries is established as the file is created. 
Specifically, if offset location F.RATT in the FDB is initialized with FD.BLK prior to the time 
the file is created, the records in the resulting file are not allowed to cross buffer boundaries. 


For an existing file, the file-attribute section of the file header block is read when the file is 
opened; thus, all attributes of that file are made known to FCS, including whether records 
within that file are allowed to cross block boundaries. 


The design of FCS requires you to use your task’s record buffer only in the event that 
records (either fixed or variable in length) cross buffer boundaries. 


e If a GET$ operation is performed in locate mode, and the record is contained entirely within 
the FSR block buffer, the address of the record within the FSR block buffer and the size of 
that record are returned to the associated FDB in offset locations F.NRBD+2 and F.NRBD, 
respectively. However, if that record crosses buffer boundaries, it is moved to your task’s 
record buffer. In this case, the address of your task’s record buffer and the size of the record 
are returned to offset locations F.NRBD+2 and F.NRBD, respectively. 
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In summary, if the potential exists for crossing buffer boundaries during GET$ operations in 
locate mode, then your task’s record buffer descriptors must be supplied through any available 
means to appropriately initialize offset locations F.URBD+2 and F.URBD in the associated FDB. 


3.10 GET$R—Read Logical Record in Random Mode 


The GET$R macro reads fixed-length records from a file in random mode. Thus, by definition, 
issuing this macro requires that you be familiar with the structure of the file to be read and, 
furthermore, that you be able to specify precisely the number of the record to be read. 


The GET$ and GET$R macros are identical, except that the parameter list of GET$R includes 
the specification of the desired record number. If the desired record number is already present 
in the FDB (at offset locations F.RCNM and F.RCNM+2), then GET$ may be used. If, however, 
the record access byte in the FDB (offset location F.RACC) has not been initialized for random 
access operations with FD.RAN in the FDRC$A, the FDRC$R, or the generalized OPEN$x 
macro, then neither GET$ nor GET$R will read the desired record. 


The GET$R macro takes two more parameters in addition to those specified in the GET$ macro. 


Format 
GET$R_ fdb,urba,urbs,Ircnm,hrcenm,err 


Parameters 


Ircnm 
Specifies the low-order 16 bits of the number of the record to be read. This value, which 
must be specified, is stored in offset location F.RCNM+2 in the FDB. The GET$R macro call 
seldom requires more than 16 bits to express the record number. A logical record number 
up to 65,5363) may be specified through this parameter. If this parameter is not sufficient 
to completely express the magnitude of the record number, the hrcnm parameter must also 
be specified. 


hrenm 
Specifies the high-order 15 bits of the number of the record to be read. This value is stored 
in FDB offset location F.RCNM. If specified, the combination of this parameter and the 
Ircnm parameter determines the number of the desired record. Thus, an unsigned value 
having a total of 31 bits of magnitude may be used in defining the record number. 


If this parameter is not specified, offset location F.RCNM retains its initialized value of 0. 


If you use F.RCNM to specify a desired record number for any given GET$R operation, this 
cell must be cleared before issuing a subsequent GET$R macro that requires 16 bits or less 
to express the desired record number; otherwise, any residual value in F.RCNM yields an 
incorrect record number. 
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If the Ircnm and hrenm parameters are not specified in a subsequent GET$R macro, the next 
sequential record is read because the record number in offset locations F.RCNM+2 and F.RCNM 
is increased by 1 with each GET$ operation. In the case of the first GET$R, after opening the 
file, record number 1 is read because the record number has been initialized to 0 by the OPEN 
macro. If a record other than the next sequential record is to be read, you must explicitly specify 
the number of the desired record. 


The statements listed at the end of this section represent the use of the GET$R macro. 


Note 


RO can be used only to pass the FDB address parameter. Any other use of RO when issuing the 
GET$R macro will fail. 


Examples 
CET$R #INFDB,#RECBUF , #160. ,#1040., ,ERROR 


Expresses, through the first of two available fields for this purpose, the desired number to 
be read, that is, 10409. The second field is not required and is therefore reflected as a null 
specification. The number of the desired record to be read, that is, 1040j0, is expressed through 
the first of two available fields; the second field is not required and is therefore reflected as a 
null specification. 


GET$R #FDBADR,#RECBUF , #160. ,R3 


Reflects the use of general register 3 in specifying the logical record number. This register, or 
any other location so used, must be preset with the desired record number before issuing the 
GET$R macro. 


3.11 GET$S—Read Logical Record in Sequential Mode 


The GET$S macro reads logical records from a file in sequential mode. Although the routine 
invoked by the GET$S macro requires less memory than that invoked by GET$ (see Section 3.9), 
GET$S has the same format and takes the same parameters. The GET$S macro is specifically 
for use in an overlaid environment in which the amount of memory available to the program 
is limited and files are to be read in strictly sequential mode. 


If both GET$S and PUT$S are to be used by the program, note that the savings in memory 
usage over GET$ and PUT$ can be realized only if GET$S and PUT$S are placed on different 
branches of the overlay structure. 
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3.12 PUTS—wWrite Logical Record 


The PUT$ macro writes logical records to a file. If operating in random access mode, the number 
of the record to be written is maintained by FCS in offset locations F.RCNM and F.RCNM:#2 of 
the associated File Descriptor Block (FDB). File Control Services (FCS) increases this value by 
1 after each PUT$ or PUT$R operation to point to the next sequential record position. Thus, 
unless your program alters this value before issuing another PUT$ or PUT$R operation, the 
next record in sequence is written. 


For PUT$ operations, offset locations F.NRBD+2 and F.NRBD in the associated FDB must contain 
the address and the size, respectively, of the record to be written. The distinction between 
move mode and locate mode for PUT$ operations relates to the building or the assembling of 
the data into a record. Specifically, in move mode the record is built in a buffer of your choice. 
This buffer is not necessarily your task’s record buffer previously described in the context of 
record I/O operations. In other words, you can build records in an area of a program apart 
from that normally defined by your task’s record buffer descriptors in the FDB (F.URBD+2 and 
F.URBD). In this case, you specify the address of the record buffer so used and the size of the 
record in the PUT$ macro, and the record thus built is then moved into the FSR block buffer. 


In locate mode, however, the record is built at the address specified by the contents of offset 
location F.NRBD+2, and only the record size need be specified in the PUT$ macro. Then, if the 
record so built is not already in the FSR block buffer, it is moved there as the PUT$ operation 
is performed. 


If the records in the file are sequenced records, the field FSEQN in the FDB contains the 
sequence value, which you can modify. 


PUT$ operations are fully synchronous; that is, record I/O operations are completed before 
control is returned to your task’s program. 


A random PUT$ operation in locate mode requires the use of the .POSRC routine. This 
operation is described in detail in Chapter 4. Specific FDB requirements for PUT$ operations 
are presented in Section 3.12.2. 


3.12.1 Format of PUTS Macro 


The format of the PUT$ macro is shown next. 


Format 
PUT$ fdb,nrba,nrbs,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


nrba 
Specifies the symbolic address of the next record buffer, that is, the address of the record 
to be PUT$. This parameter initializes FDB offset location F.NRBD+2. 
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nrbs 
Specifies the size of the next record buffer, that is, the length of the record to be PUTS. 
This parameter initializes FDB offset location F.NRBD. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


The examples listed at the end of this section show how the PUT$ macro may be used in a 
program. 


Note 


RO can only be used to pass the FDB address parameter as shown in the third example; it 
cannot be used to pass any other parameter in the PUT$ macro. 


Examples 
PUTS #FDBADR, , ,ERRRT 


Shows the next record buffer address (nrba parameter) and the next record buffer size (nrbs 
parameter) are null. These null specifications imply that the current values in offset locations 
F.NRBD+2 and F.NRBD of the associated FDB are suitable to the current operation. Note also 
that fixed-length records could also be written in locate mode by issuing this macro. 


PUT$ , #160. , ERRRT 


Contains null specifications in the first two parameter fields, assuming that RO currently contains 
the address of the associated FDB and that variable-length records are to be written to the file. 


PUT$ RO 


Specifies only the address of the FDB; all other parameter fields are null. 


3.12.2 The FDB Relevant to PUTS Operations 


This subsection highlights aspects of PUT$ operations in move and locate mode that have a 
bearing on the associated FDB. 


The conditions under which your task’s record buffer is or is not used are summarized. As 
is the case for GET$ operations, if your task’s record buffer is required for PUT$ operations, 
the buffer descriptors (that is, the urba and urbs parameters) may be supplied to the associated 
FDB through the FDRC$A, the FDRC$R, or the generalized OPEN$x macro. In any case, offset 
locations F.URBD+2 and F.URBD must be appropriately initialized if PUT$ operations require 
the utilization of your task’s record buffer. Note, however, that PUT$ operations in move mode 
never require a record buffer. 


If your task’s record buffer is required, the specified size of that buffer (that is, the urbs 
parameter) always determines the size of the largest record that can be written to the specified 
file. 


Whether in move or locate mode, a PUT$ operation uses the information in offset locations 
F.NRBD+2 and F.NRBD, that is, the next record buffer descriptors, to determine whether the 
record must be moved into the FSR block buffer. In the event that the record does have to be 
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moved, and the size of that record is such that it cannot fit in the space remaining in the FSR 
block buffer, one of the following two possible operations is performed: 


e If records are allowed to cross block boundaries, then the first part of the record is moved 
into the FSR block buffer, thereby completing a virtual block. That block buffer is then 
written out to the volume, and the remaining portion of the record is moved into the 
beginning of the next FSR block buffer. 


e If records are not allowed to cross block boundaries (because of the file attribute FD.BLK 
specified in the associated FDB), then the FSR block buffer is written out to the volume, as 
is, and the entire record is moved into the beginning of the next FSR block buffer. 


3.12.2.1 PUTS Operations in Move Mode 


A PUT$ operation in move mode (see Chapter 2) is driven by specifying in each PUT$ macro 
the address and the size of the record to be written. Then, as the PUT$ operation is performed, 
FCS moves the record into the appropriate area of the FSR block buffer. 


In summary, the following generalizations apply for PUTS operations in move mode: 


° Your task’s record buffer descriptors need not be present in the FDB because the programmer 
is dynamically specifying the address and the length of the record to be written at each 
issuance of a PUT$ macro. The values specified dynamically update offset locations 
F.NRBD+2 and F.NRBD in the associated FDB. 


° If the file consists of fixed-length records, then the generalized OPEN$x macro (see 
Section 3.1) initializes offset location F.NRBD with the appropriate record size, as defined 
by the contents of offset location F.RSIZ. Thus, the size of the record need not be specified 
as the nrbs parameter in any PUT$ macro involving this file. 


e If the variable-length records are being used during a PUT$ operation, the size of each 
record must be specified as the nrbs parameter in each PUT$ macro call involving this file, 
thus setting offset location F.NRBD to the appropriate record size. 


3.12.2.2 PUTS Operations in Locate Mode 


Your task’s record buffer is required for PUT$ operations in locate mode (see Chapter 2) only 
when the potential exists for records to cross buffer boundaries. If there is insufficient space 
in the FSR block buffer to accommodate the building of the next record, you must provide a 
buffer in your task’s memory space to build that record. 


When a file is initially opened for PUT$ operations in locate mode, FCS sets up offset location 
F.NRBD+2 to point to the area in the FSR block buffer where the next record is to be built. 
Then, each PUT$ operation thereafter in locate mode updates the address value in this cell to 
point to the area in the FSR block buffer where the next record is to be built. Thus, after each 
PUT$ operation in locate mode, F.NRBD+2 points to the area where the next record is to be 
built. This logic dictates whether your record buffer is required in locate mode. 


The following generalizations apply: 


Note 


In the following discussion, reference is made to the FSR block buffer. By 
default, the block size that FCS uses is equivalent to the buffer size of the 
device on which the file is opened. If big buffering is enabled (that is, an ovbs 
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parameter value is specified in the FDBF$x macro, as described in Chapter 2) 
the FSR block buffer will be more than one block long. As a result, it may 
not be necessary to move a record even though it crosses block boundaries 
because both blocks are currently within the FSR block buffer space. Thus, 
moves are only necessary when the record crosses a buffer boundary, which is 
not necessarily the same as a block boundary in a big-buffered file. 


e If your task is performing a PUT$ operation for fixed-length records and they fit evenly 
within the FSR block buffer, your task’s record buffer is not required. 


¢ If a fixed-length record crosses block boundaries, your task’s record buffer descriptors must 
be present in offset locations F.URBD+2 and F.URBD of the associated FDB. In this case, 
after FCS determines that the record cannot fit in the FSR block buffer, FCS sets offset 
location F.NRBD+2 to point to your task’s record buffer. Then, when the record is processed 
with the PUT$ operation, it is moved from your record buffer to the FSR block buffer. 


* If a variable-length record is processed with the PUTS operation, the potential exists for 
crossing block boundaries. In this case, your task’s record buffer descriptors must be present 
in offset locations F.URBD+2 and F.URBD of the associated FDB. Moreover, the size of each 
variable-length record must be specified as the nrbs parameter in each PUT$ macro. 


Determining if FCS points offset location F.NRBD+2 to the FSR block buffer for the PUT$ 
operation or to your task’s record buffer is based on whether there is enough room in the 
FSR block buffer to accommodate the record. 


Because the records are variable in length, you can assume that the largest possible record 
is PUT$, as defined by the size of your task’s record (F.URBD). Thus, if a record of this 
defined size cannot fit in the space remaining in the FSR block buffer, FCS sets offset 
location F.NRBD+2 to point to your task’s record buffer. 


Each PUT$ operation in locate mode sets up the FDB for the next PUT$ operation. The specified 
record size is used by FCS as the worst-case condition in determining whether sufficient space 
exists in the FSR to build the next record. 


If variable-length records are being processed that are shorter than the largest defined record 
size, FCS may move records unnecessarily from your task’s record buffer to the FSR block 
buffer. For example, assume that your task has allocated a 132-byte record buffer and further, 
that the available remaining space in the FSR block buffer is less than 132 bytes. In this case, 
FCS continues to point to your task’s record buffer for PUT$ operations, even if you continue 
to perform PUT$ operations with short (10- or 20-byte) records. Thus, some unavoidable 
movement of records takes place in locate mode. 


If the largest record that you intend to process with the PUT$ operation is 80 bytes, for example, 
then the largest defined record size should not be specified as 132 bytes (or any length larger 
than that intended to be processed with the PUT$ operation). Aside from having to allocate 
a smaller record buffer in your task, PUT$ operations in locate mode are more efficient if this 
precaution is observed. Exercising care in this regard reduces the tendency to move records 
from your task’s record buffer to the FSR block buffer when they might otherwise be built 
directly in the FSR block buffer. 
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3.13 PUTSR—Write Logical Record in Random Mode 


The PUT$R macro writes fixed-length records to a file in random mode. As noted in 
Section 3.10, the GET$R macro, operations in random access mode require you to be very 
familiar with the contents of such files. The PUT$R macro also relies entirely on you to specify 
the number of the record before a specified PUT$ operation can be performed. Because the 
usual purpose of a PUT$R operation is to update known records in a file, it is assumed that 
you also know the number of such records within the file. 


The PUT$ and PUT$R macros are identical, except that PUT$R allows the specification of 
the desired record number. If the desired record number is already present in the FDB (at 
offset locations F.RCNM and F.RCNM+2), then PUT$ and PUT$R may be used interchangeably. 
However, if the record access byte in the FDB (offset location F.RACC) has not been initialized 
for random access operations with FD.RAN in the FDRC$A, the FDRC$R, or the generalized 
OPENS$x macros, then neither PUT$ nor PUT$R will write the desired record. 


The PUT$R macro takes two more parameters in addition to those specified in the PUT$ macro. 


Format 
PUT$R_ fdb,nrba,nrbs,lrcnm,hrcenm,err 


Parameters 


Irenm 
Specifies the low-order 16 bits of the number of the record to be processed. This 
parameter serves the same purpose as the corresponding parameter in the GET$R macro (see 
Section 3.10), except that it identifies the record to be written. 


hrenm 
Specifies the high-order 15 bits of the number of the record to be processed. This parameter 
serves the same purpose as the corresponding parameter in the GET$R macro, except that 
it identifies the record to be written. 


If this parameter is not specified, offset location F.RCNM retains its initialized value of 0. 


If F.RCNM is used in expressing a desired record number for any given PUT$R operation, 
you must clear this cell before issuing a subsequent PUT$R macro that requires 16 bits 
or less in expressing the desired record number; otherwise, any residual value in F.RCNM 
results in an incorrect record number. 


The Ircnm and hrenm parameters initialize offset locations F.RCNM+2 and F.RCNM, respectively, 
in the associated FDB. If these values are not specified in a subsequent PUT$R macro, the next 
sequential record is written because FCS increases the record number by 1 in these cells after 
each PUT$ operation. In the case of the first PUT$R after opening the file, record number 1 
is written. Note that this is true even if the file has been opened for an append operation 
(OPEN$A). If a record other than the next sequential record is to be written, you must explicitly 
specify the number of the desired record. 


Examples listed at the end of this section show how the PUT$R macro may be used in a 
program. 
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Notes 


1. A random mode PUT$R operation executed in locate mode must be preceded by a call to 
-POSRC. Because locate mode allows you to store data directly into the block buffer, the 
file must be positioned so that the desired record position is in fact in the block buffer. See 
Chapter 4 for further details. 


2. You can use RO only to pass the FDB address. Any other use of RO when you issue the 
PUT$R macro will fail. 


Examples 
PUT$R § #QUTFDB, #RECBUF, , #12040. , ,ERRLOC 


Indicates that you are specifying the address of the record. You can determine this by the 
presence of RECBUF as the next record buffer address (nrba). Although specifying this address 
repeatedly is unnecessary, it is not invalid. Normally, a buffer address is specified dynamically 
because other PUT$ macro calls may be referencing different areas in memory; thus, the address 
of the record must be explicitly specified in each PUT$ macro. Note also that the next record 
buffer size (nrbs) parameter is null, because this parameter is required only in the case of writing 
variable-length records. Also, the second of the two available parameters for defining the record 
number is null. 


PUT$R #FDBADR , #RECBUF, , R4 
PUT$R #FDBADR , #RECBUF , , LRN 
Indicates that R4 and a memory location (LRN) are used to specify the logical record number. 


Such a specification assumes that you have preset the desired record number in the referenced 
location. 


3.14 PUT$S—Write Logical Record in Sequential Mode 


The PUT$S macro writes logical records to a file in sequential mode. Although the 
routine invoked by the PUT$S macro requires less memory than that invoked by PUT$ (see 
Section 3.12), PUT$S has the same format and takes the same parameters. The PUT$S macro 
is specifically for use in an overlaid environment in which the amount of memory available to 
the program is limited and files are to be written in strictly sequential mode. 


If both GET$S and PUT$S are to be used by the program, the savings in memory utilization 
over GET$ and PUT$ are realized only if GET$S and PUT$S are placed on different branches 
of the overlay structure. 
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3.15 READS—Read Virtual Block 


The READ$ macro reads a virtual block of data from a block-oriented device (for example, a 
magnetic tape, a disk, or DECtape). In addition, if certain optional parameters are specified in 
the READ$ macro, status information is returned to the I/O status block (IOSB) (see Chapter 2) 
or the program traps to an asynchronous system trap (AST) service routine, which you coded, 
at the completion of block I/O operations (see Chapter 2). 


In issuing the READ$ (or WRITE$) macro, you are responsible for synchronizing all block I/O 
operations. For this reason, the WAIT$ macro is provided (see Section 3.17), which allows 
you to suspend program execution until a specified READ$ or WRITE$ operation has been 
completed. It is important, however, that you test the contents of F.ERR in the File Descriptor 
Block (FDB) for error codes immediately after issuing the READ$ or WRITES call as well as 
on return from the WAIT$ call. When errors occur during multiple-block transfers, the second 
word of the IOSB will contain the number of bytes transferred before the error occurred. The 
READ$ or WRITE operations can return error codes distinct from those that can be present on 
completing a WAIT$ operation. For example, IE.EOF will be returned upon completion of the 
READ$ operation but not upon completion of the WAIT$ operation. 


When your task issues the WAIT$ macro with a READ$ (or WRITE$) macro, you must ensure 
that the event flag number and the IOSB address specified in both macro calls are the same. 


When the WTSE$ macro waits for I/O completion, the issuing task must check I/O errors by 
examining the IOSB (defined by the task). (The IOSB is described in Chapter 2.) When WTSE$ 
is used, File Control Services (FCS) will not return a completion code to offset F.ERR in the 
FDB. 


3.15.1 Format of READS Macro 


Note in the following format that the parameters of the READ$ macro are identical to those of 
the FDBK$A or the FDBK$R macro, with the exception of the fdb and err parameters. Certain 
FDB parameters may be set at assembly time (FDBK$A), initialized at run time (FDBK$R), or 
set dynamically by the READ$ macro. Certain information must be present in the FDB before 
the specified READ$ (or WRITE$) operation can be performed. These requirements are noted 
in Section 3.15.2. 


Format 
READ$_ fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


bkda 
Specifies the symbolic address of the block I/O buffer in your program. This parameter 
need not be specified if offset location F.BKDS+2 has been previously initialized through 
either the FDBK$A or the FDBK$R macro. 
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bkds 
Specifies the size (in bytes) of the virtual block to be read. This parameter need not be 
specified if offset location F.BKDS has been previously initialized through either the FDBK$A 
or the FDBK$R macro. The maximum block size that may be specified for file-structured 
devices is 32,256 bytes. 


bkvb 
Specifies the symbolic address of a 2-word block in your program containing the number of 
the virtual block to be read. This parameter causes offset locations F.BKVB and F.BKVB+2 
to be initialized with the virtual block number; F.BKVB+2 contains the low-order 16 bits of 
the virtual block number, and F.BKVB contains the high-order 15 bits. 


As noted in connection with the FDBK$A macro described in Chapter 2, assembly-time 
initialization of the virtual block number in the FDB is ineffective because the generalized 
OPEN$x macro sets the virtual block number in the FDB to 1. 


The virtual block number can be made available to FCS only through the FDBK$R macro 
or the I/O-initiating READ$ (or WRITE$) macro after the file has been opened. The virtual 
block number is created as described in Chapter 2. 


The READ$ function checks the specified virtual block number to ensure that it does not 
reference a nonexistent block, that is, a block beyond the end of the file. If the virtual 
block number references nonexistent data, an end-of-file (IE.EOF) error indication is returned 
to offset location F.ERR of the associated FDB; otherwise, the READ$ operation proceeds 
normally. If the total number of bytes goes beyond the end of the file, then as many blocks 
as exist are read and the byte count of the shortened transfer is returned in I/O STATUS+2. 
No error condition occurs, so you must check the count on each READ. An end-of-file 
indication is returned only if no blocks can be read. 


If the virtual block number is not specified through any of the available means identified 
already, sequential operation results by default, beginning with virtual block number 1. 
The virtual block number is incremented by the number of blocks read after each READ$ 
operation is performed. 


bkef 
Specifies the event flag number to be used for synchronizing block I/O operations. This 
event flag number is used by FCS to signal the completion of the specified block I/O 
operation. The event flag number, which may also be specified in either the FDBK$A or 
the FDBK$R macro, initializes FDB offset location F.BKEF; if specified, this parameter need 
not be included in the READ$ (or WRITE$) macro. 


If this optional parameter is not specified through any available means, event flag 3210 is 
used by default. The function of an event flag is discussed in further detail in Chapter 2. 


bkst 
Specifies the symbolic address of the IOSB in your task (see Chapter 2). This parameter, 
which initializes offset location F.BKST, is optional. The IOSB is filled in by the system 
when the requested block I/O transfer is completed, indicating the success or failure of the 
requested operation. 
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The address of the IOSB may also be specified in either the FDBK$A or the FDBK$R macro. 
If the address of this 2-word structure is not supplied to FCS through any of the available 
means, status information cannot be returned to your program. Regardless, the event flag 
specified through the bkef parameter is set to indicate block I/O completion, but, without 
an JOSB, your program must assume that the operation (for example, READ$ or WRITE$) 
was successful. 


bkdn 
Specifies the symbolic entry point address of an AST service routine (see Chapter 2). If this 
parameter is specified, a trap occurs upon completion of the specified READ$ (or WRITE$) 
operation. This parameter, which is optional, initializes offset location F.BKDN. This address 
value may also be made available to FCS through either the FDBK$A or the FDBK$R macro, 
and, if specified, need not be present in the READ$ (or WRITE$) macro call. 


If the address of an AST service routine is not specified through any available means, no 
AST trap occurs at the completion of block I/O operations. 
err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 
The examples listed at the end of this section represent READ$ macros that may be issued to 
accomplish a variety of operations. 
Note 
You can use RO only to pass the FDB address. Any other use of RO when you issue the READ$ 
macro will fail. 
Examples 
READ$ RO 


Assumes that RO contains the address of the associated FDB. Also, all other required FDB 
initialization has been accomplished through either the FDBK$A or the FDBK$R macro call. 


READ$ #INFDB,,,.,,, ERRLOC 


Shows an explicit declaration of the associate FDB and includes the symbolic address of an 
error-handling routine, which you coded. 


READ$ RO,#INBUF ,#BUFSIZ, , #22. ,#IOSADR, #ASTADR ,ERRLOC 


Shows that RO again contains the address of the associated FDB. The block buffer address 
and the size of the block are specified next in symbolic form. The address of the 2-word 
block in your program containing the virtual block number is not specified, as indicated by the 
additional comma in the parameter string. The event flag number, the address of the IOSB, 
and the address of the AST service routine then follow in order. Finally, the symbolic address 
of an optional error routine is specified. 


READ$ #INFDB,#INBUF , #BUFSIZ,#VBNADR 


Reflects, as the last parameter in the string, the symbolic address of the 2-word block in your 
program containing the virtual block number. 
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3.15.2 The FDB Relevant to READS Operations 


The READ$ macro requires that the associated FDB be initialized with certain values before it 
can be issued. You can specify these values through either the FDBK$A or the FDBK$R macro, 
or they may be made available to the FDB through the various parameters of the READ$ macro. 
The following values must be present in the FDB to enable READ$ operations to be performed: 


¢ The block buffer address (in offset location F.BKDS+2) 
¢ The block byte count (in offset location F.BKDS) 
¢ The virtual block number (in offset locations F.BKVB+2 and F.BKVB) 


Note 
When either READ$ or WRITE$ operations are performed, FCS maintains the 
end-of-file (EOF) block number field (F.EFBK) and clears the first free byte in 
the last block field (F.FFBY) in the FDB. During a READ$ operation, EOF is 
determined by the EOF block number field in F.EFBK. If desired, you can modify 
F.FFBY before closing the file by using the CLOSE$ macro call. 


3.16 WRITES —wWrite Virtual Block 


The WRITE$ macro is issued to write a virtual block of data to a block-oriented device (for 
example, magnetic tape, disk, DECtape, or DECtape II). Like the READ$ macro, if certain 
optional parameters are specified in the WRITE$ macro, status information is returned to the 
IOSB (see Chapter 2), and, at the completion of the I/O transfer, the program traps to an 
AST service routine that is supplied to coordinate asynchronous block I/O operations (see 
Chapter 2). 


Whether or not you supply the address of an AST service routine and an event flag number, 
you are responsible for synchronizing all block 1/O processing. The WAIT$ macro can be issued 
with the WRITE$ macro to suspend program execution until a program-dependent I/O transfer 
has been completed. When the WAIT$ macro is used for this purpose, the event flag number 
and the IOSB address in both macros must be the same. Again, as with READ$ operations, you 
should check for an error code immediately following the WRITE$ macro as well as on return 
from the WAIT$ macro. 


3.16.1 Format of WRITES Macro 


The WRITE$ macro takes the same parameters as the READ$ macro. The bkvb parameter 
represents the symbolic address of a 2-word block containing the number of the virtual block to 
be written. The virtual block number is incremented after each WRITE$ operation is performed. 
Format 


WRITE$ _  fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 
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bkda 
Specifies the symbolic address of the block I/O buffer in your program. This parameter 


need not be specified if offset location F.BKDS+2 has been previously initialized through 
either the FDBK$A or the FDBK$R macro. 


bkds 
Specifies the size (in bytes) of the virtual block to be written. This parameter need not be 
specified if offset location F.BKDS has been previously initialized through either the FDBK$A 
or the FDBK$R macro. The maximum block size that may be specified for file-structured 
devices is 32,256 bytes. 


bkvb 
Specifies the symbolic address of a 2-word block in your program containing the number of 
the virtual block to be written. This parameter causes offset locations F.BKVB and F.BKVB+2 
to be initialized with the virtual block number; F.BKVB+2 contains the low-order 16 bits of 
the virtual block number, and F.BKVB contains the high-order 15 bits. 


As noted in connection with the FDBK$A macro described in Chapter 2, assembly-time 
initialization of the virtual block number in the FDB is ineffective because the generalized 
OPEN$x macro sets the virtual block number in the FDB to 1. 


The virtual block number can be made available to FCS only through the FDBK$R macro 
or the I1/O-initiating WRITE$ (or READ$) macro after the file has been opened. The virtual 
block number is created as described in Chapter 2. 


If the virtual block number is not specified through any of the available means identified 
already, sequential operation results by default, beginning with virtual block number 1. The 
virtual block number is incremented by the number of blocks written after each WRITES 
operation is performed. 


bkef 
Specifies the event flag number to be used for synchronizing block I/O operations. This 
event flag number is used by FCS to signal the completion of the specified block I/O 
operation. The event flag number, which may also be specified in either the FDBK$A or 
the FDBK$R macro, initializes FDB offset location F.BKEF; if specified, this parameter need 
not be included in the WRITE$ macro. 


If this optional parameter is not specified through any available means, event flag 32;0 is 
used by default. The function of an event flag is discussed in further detail in Chapter 2. 


bkst 
Specifies the symbolic address of the IOSB in your task (see Chapter 2). This parameter, 
which initializes offset location F.BKST, is optional. The IOSB is filled in by the system 
when the requested block I/O transfer is completed, indicating the success or failure of the 
requested operation. 


The address of the IOSB may also be specified in either the FDBK$A or the FDBK$R macro. 
If the address of this 2-word structure is not supplied to FCS through any of the available 
means, status information cannot be returned to your program. Regardless, the event flag 
specified through the bkef parameter is set to indicate block I/O completion, but, without 
an IOSB, your program must assume that the WRITE$ operation was successful. 


3-34 File-Processing Macros 


bkdn 
Specifies the symbolic entry point address of an AST service routine (see Chapter 2). If this 
parameter is specified, a trap occurs upon completion of the specified WRITE$ operation. 
This parameter, which is optional, initializes offset location F.BKDN. This address value 
may also be made available to FCS through either the FDBK$A or the FDBK$R macro, and, 
if specified, need not be present in the WRITE$ macro call. 


If the address of an AST service routine is not specified through any available means, no 
AST trap occurs at the completion of block I/O operations. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


When this macro is issued, the virtual block number (that is, the bkvb parameter) is checked to 
ensure that it references a block within the file’s allocated space; if it does, the block is written. 
If the specified block is not within the file’s allocated space, FCS attempts to extend the file. 
If this attempt is successful, the block is written; if the attempt is unsuccessful, an error code 
indicating the reason for the failure of the extend operation is returned to the IOSB and to offset 
location F.ERR of the associated FDB. 


If FCS determines that the file must be extended, the actual extend operation is performed 
synchronously. After the extend operation has been successfully completed, the WRITE$ 
operation is queued, and only then is control returned to the instruction immediately following 
the WRITE$ macro. 


The examples listed at the end of this section show how the WRITE$ macro may be used in a 
program. 

Note 

You can use RO only to pass the FDB address. Any other use of RO when you issue the WRITE$ 


macro will fail. 


Examples 
WRITE$ RO 


Specifies only the FDB address and assumes that all other required values are present in the 
FDB. 


WRITE$ #OUTFDB, #OUTBUF , #BUFSIZ, #VBNADR, #22. 


Reflects explicit declarations for the FDB, the block buffer address, the block buffer size, the 
virtual block number address, and the event flag number for signaling block I/O completion. 


WRITE$ RO,,,,#22.,#IOSADR,#ASTADR,ERRLOC 


Shows null specifications for three parameter fields, then continues with the event flag number, 
the address of the IOSB, and the address of the AST service routine. Finally, it specifies the 
address of an error-handling routine, which you coded. 
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3.16.2 The FDB Relevant to WRITES Operations 


WRITE$ operations require the presence of the same information in the FDB as READ$ operations 
(see Section 3.15.2). 


3.17 WAITS—Wait-for Block |/O Completion 


The WAIT$ macro, which is issued only with READ$ and WRITE$ operations, suspends 
program execution until the requested block I/O transfer is completed. This macro may be used 
to synchronize a block 1/O operation that depends on the successful completion of a previous 
block I/O transfer. 


As noted in Section 3.15, the READ$ macro, you can specify an event flag number through 
the bkef parameter. This event flag number is used during READ$ (or WRITES) operations to 
indicate the completion of the requested transfer. If desired, you can issue a WAIT$ macro 
(specifying the same event flag number and IOSB address) following the READ$ (or WRITE$) 
macro. 


The READ$ (or WRITE$) operation is initiated in the usual manner, but the Executive suspends 
program execution until the specified event flag is set, indicating that the 1/O transfer has been 
completed. The system then returns information to the IOSB, indicating the success or failure 
of the operation. File Control Services (FCS) then moves the IOSB success or failure indicator 
into offset location F.ERR of the associated File Descriptor Block (FDB). FCS returns with the 
carry condition code in the Processor Status Word (PSW) cleared if the operation is successful, 
or set if the operation is not successful. Task execution then continues with the instruction 
immediately following the WAIT$ macro. 


The system returns the final status of the I/O operation to the IOSB (see Chapter 2) upon 
completion of the requested operation. A positive value (+) indicates successful completion, 
and a negative value (-) indicates unsuccessful completion. 


Event flags are discussed in further detail in Chapter 2. 


3.17.1 Format of WAITS Macro 
The format of the WAIT$ macro follows. 


Format 
WAIT$ __ fdb,bkef,bkst,err 


Parameter 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


bkef 
Specifies the event flag number to be used for synchronizing block I/O operations. The 
WAIT$ macro causes task execution to be suspended by invoking the WTSE$ (Wait-for 
Single Event Flag) system directive. This parameter must agree with the corresponding 
(bkef) parameter in the associated READ$ or WRITE$ macro. 
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If this parameter is not specified, either in the WAIT$ macro call or the associated READ$ 
or WRITE macro, FDB offset location F.BKEF is assumed to contain the desired event flag 
number, as previously initialized through the bkef parameter of the FDBK$A or the FDBK$R 
macro. 


bkst 
Specifies the symbolic address of the IOSB in your program (see Chapter 2). Although this 


parameter is optional, if it is specified, it must agree with the corresponding (bkst) parameter 
in the associated READ$ or WRITE$ macro. 


If this parameter is not specified, either in the WAIT$ macro call or the associated READ$ 
or WRITE$ macro, FDB offset location F.BKST is assumed to contain the address of the 
IOSB, as previously initialized through the bkst parameter of the FDBK$A or the FDBK$R 
macro. If F.BKST has not been initialized, no information is returned to the IOSB. 


err 

Specifies the symbolic address of an optional error-handling routine, which you coded. 
The examples listed at the end of this section show how the WAIT$ macro may be used in a 
program. 
Note 
You can use RO only to pass the FDB address. Any other use of RO when you issue the WAIT$ 
macro will fail. 
Examples 
WAIT$ RO 


Assumes that RO contains the address of the associated FDB; furthermore, because no flag 
number (bkef parameter) is specified, offset location F.BKEF is assumed to contain the desired 
event flag number. If this cell in the FDB contains 0, event flag number 3219 is used by default. 


WAIT$ #INFDB,#25. 


Shows an explicit specification of the File Descriptor Block (FDB) address and specifies 2549 as 
the event flag number. Again, in this example, the FDB is assumed to contain the address of 
the IOSB. 


WAIT$ RO,#25.,#IOSTAT 


Shows an explicit specification for the address of the IOSB, which is in contrast to the second 
example. 


WAIT$ RO, ,#IOSTAT,ERRLOC 


Contains a null specification for the event flag number, and, in addition, specifies the address 
of an error-handling routine, which you coded. 


Please note that the WAIT$ macro associated with a given READ$ or WRITE$ operation need 
not be issued immediately following the macro to which it applies. For example, the following 
sequence is typical: 


1. Issue the desired READ$ or WRITE$ macro. 
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2. Perform other processing that is not dependent on the completion of the requested block 
I/O transfer. 


3. Issue the WAIT$ macro. 


4. Perform the processing that is dependent on the completion of the requested block I/O 
transfer. 


When you perform several asynchronous transfers in the same general sequence described 
previously, you must maintain a separate buffer, IOSB, and event flag for each operation. If 
you intend to wait for the completion of a given transfer, the appropriate event flag number 
and IOSB address must be specified in the associated WAIT$ macro. 


3.18 DELETS—Delete Specified File 


The DELET$ macro causes the directory information for the file associated with the specified 
FDB to be deleted from the appropriate User File Directory (UFD). The space occupied by the 
file is then deallocated and returned for reallocation to the pool of available storage on the 
volume. 


This macro can be issued for a file that is either open or closed. If issued for an open file, 
that file is then closed and deleted; if issued for a closed file, that file is deleted only if the 
filename string specified in the associated data-set descriptor or default filename block contains 
an explicit file version number (including 0 and -1). 


Format 
DELET$ __ fdb,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


Note 


If the DELET$ macro is issued for use with a file containing sensitive information, it is 
recommended that you zero the file before closing it. (Although DELET$ logically removes a 
file, the information physically remains on the volume until written over with another file, and 
could be analyzed by unauthorized user tasks.) 


Examples 

DELET$ RO 

DELET$ #0UTFDB,ERRLOC 
DELET$ RO,ERRLOC 


Shows how the DELET$ macro may be used in a program. 
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Chapter 4 


File Control Routines 


This chapter describes a set of file control routines that you can invoke in MACRO-11 programs 
to perform the following functions: 


Read or write default directory string descriptors in program section $$FSR2. 

Read or write the default User Identification Code (UIC) word in program section $$FSR2. 
Read or write the default file protection word in program section $$FSR2. 

Read or write the file owner word in program section $$FSR2. 


Convert a directory string from American Standard Code for Information Interchange (ASCII) 
to binary or from binary to ASCII. 


Fill in all or part of a filename block from a data-set descriptor or default filename block. 
Find, insert, or delete a directory entry. 

Set a pointer to a byte within a virtual block or to a record within a file. 

Mark a place in a file for a subsequent OPEN$x operation. 

Issue an I/O command and wait for its completion. 

Rename a file. 

Extend a file. 

Truncate a file. 

Mark a temporary file for deletion. 

Delete a file by filename block. 


Perform device-specific control functions. 
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4.1 Calling File Control Routines 


The CALL macro invokes file control routines (JSR PC, dst). The Task Builder (TKB) 
includes these routines from the system object library ((1,1JSYSLIB.OLB) at task-build time 
and incorporates them into your task. Your task calls the following file control routines: 


CALL .RDFDR 
CALL .EXTND 


Before your task issues the CALL macro, certain file control routines require that specific registers 
be preset with requisite information. The descriptions of the respective routines identify these 
requirements. Upon return to your task, all task registers are preserved except for those that 
have been explicitly specified as changed. 


If a file control routine detects an error, it sets the Carry bit indication to FDB offset location 
F.ERR. However, certain file control routines do not return error indications even if one is 
present. The following file control routines are listed according to whether they return error 
indications. 


Normal Error Return 


(Carry Bit and F.ERR) No Error Return 
.ASCPP -RDFDR 
-PARSE .WDFDR 
.PRSDV .RDFUI 
.PRSDI .WDFUI 
.PRSDV .RDFFP 
.ASLUN .WDFFP 
.FIND .RFOWN 
.ENTER .WFOWN 
-REMOV -PPASC 
.GTDIR -.MARK 
.GTDID 

.POINT 

.POSRC 

.POSIT 

.XQIO 

.RENAM 

.EXTND 

-TRNCL 
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Normal Error Return 
(Carry Bit and F.ERR) No Error Return 


-MRKDL 
.DLFNB 
.CTRL 


Appendix K lists the error codes that the routines return in a File Descriptor Block (FDB) offset 
location F.ERR. 


4.2 Default Directory String Routines 
The .RDFDR and .WDFDR routines read and write directory string descriptors. 


4.2.1 .RDFDR—Read $$FSR2 Default Directory String Descriptor 


Your task calls the .RDFDR routine to read default directory string descriptor words previously 
written by the .WDFDR routine into program section $$FSR2 of the file storage region (FSR). 
These descriptor words define the address and the length of an ASCII string that contains the 
default directory string. This directory string is the default directory that File Control Services 
(FCS) uses when a directory is not specified in a data-set descriptor. 


If you have not established default directory string descriptor words in program section $$FSR2 
by using the .WDFDR routine described in the following text, the descriptor words in program 
section $$FSR2 are null. FCS uses a default directory (when one is not specified in a data-set 
descriptor) corresponding to the UIC under which the task is running. 


When called, the .RDFDR routine returns values in the following registers: 
R1 Contains the size (in bytes) of the default directory string in program section $$FSR2. 


R2 Contains the address of the default directory string in program section $$FSR2. If no 
default directory string descriptor words have been written by .WDFDR, R2 equals 0. 


4.2.2 .WDFDR—Write New $SFSR2 Default Directory String Descriptor 


Your task calls the .WDFDR routine to create default directory string descriptor words in program 
section $$FSR2. For example, if your program is to operate on files in the directory [220,220], 
regardless of the UIC under which the program runs, you can establish default directory string 
descriptor cells in program section $$FSR2 to point to this alternate directory string [220,220] 
created elsewhere in the program. To do this, first create the desired directory string through an 
-ASCII directive. Then, by calling the .WDFDR routine, you can initialize the default directory 
string descriptor cells in program section $$FSR2 to point to the new directory string. 


Assume that the task is currently running under default UIC [200,200]. You define a new 
directory string by issuing the following MACRO-11 directive: 


NEWDDS : -ASCII /[220,220]/ 


By calling the .WDFDR routine, you initialize string descriptor cells in program section $$FSR2 
to point to the new directory string. 
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You must preset the following registers before your task calls the .WDFDR routine: 
Ri Must contain the size (in bytes) of the new directory string. 


R2 Must contain the address of the new directory string. 


Note 


Establishing default directory string descriptor words in program section $$FSR2 does not change 
the default UIC in program section $$FSR2 or the task’s privileges. 


4.3 Default UIC Routines 


The .RDFUI and .WDFUI routines read and write the default UIC maintained in program section 
$$FSR2 of the FSR. Unlike the default directory string descriptor that describes an ASCII string, 
the default UIC is maintained as a binary value with the format shown in Figure 4-1. 


Figure 4-1: Default UIC Format 


Bit 15 87 0 
ee ee 
2K-5971-HC 


The default UIC in program section $$FSR2 provides directory identification information for a 
file being accessed. FCS uses the default UIC only when all other sources of such information 
have failed to specify a directory (refer to Section 4.7.1.2). FCS never uses the default UIC to 
establish file ownership or file access privileges. 


Unless you change the default UIC through the .WDFUI routine described in the following text, 
the default UIC in program section $$FSR2 always corresponds to the UIC under which the 
task is running. 


4.3.1 .RDFUI—Read Default UIC 
Your task calls the .RDFUI routine to return the default UIC as follows: 


R1 Contains the binary-encoded default UIC maintained in program section $$FSR2. 


4.3.2 .WDFUI—Write Default UIC 
Your task calls the .WDFUI routine to create a new default UIC in program section $$FSR2. 
You must preset the following register before calling the .WDFUI routine: 


R1 = Must contain the binary representation of a UIC. 


Note 


The .WDFUI routine overrides any default UIC descriptor in program section $$FSR2 that was 
previously created by the .WDFDR routine. 
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4.4 Default File Protection Word Routines 


The .RDFFP and .WDFFP routines described in the following text read and write the default file 
protection word in a location in program section $$FSR2 of the FSR. FCS uses this word only 
when a file is created (for example, by the OPEN$W macro call) to establish the default file 
protection values for the new file. Unless altered, this value constitutes the default file protection 
word for that file. If the value is -1, it indicates that the volume default file protection value is 
to be used for the new file. 


The default file protection word has four file protection categories: world, group, owner, and 
system. The format of the default file protection is shown in Figure 4-2. 


Figure 4-2: File Protection Word Format 


Bit 15 12 11 8 7 43 0 


j wera | cou | owner | system | 


ZK-5972-HC 


Each of these four file protection categories has four bits; each bit represents the kind of access 
allowed to a file, as shown in Figure 4-3. 


Figure 4-3: Fite Protection Access Bits 


Bit 3 2 1 0 


2K-5973-HC 


A bit value of 0 indicates that the corresponding file access is to be allowed; a bit value of 1 
indicates that the access is to be denied. 


4.4.1 .RDFFP—Read S$SFSR2 Default File Protection Word 


You call the .RDFFP routine to read the default file protection word in program section $$FSR2 
of the FSR. No registers need be set before calling this routine. 


When called, the .RDFFP routine returns the following information: 
Rl _—_ Contains the default file protection word from program section $$FSR2. 
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4.4.2 .WDFFP—Write New S$SFSR2 Default File Protection Word 


You use the .WDFFP routine to write a new default file protection word into program section 
$$FSR2. 


You must preset the following register before calling the .WDFFP routine: 


R1 Must contain the new default file protection word to be written into program section 
$$FSR2. If this register is set to -1, the default file protection values established through 
the appropriate operating system command will be used in creating all subsequent new 
files. 


4.5 File Owner Word Routines 


The file owner word, like the default file protection word, is a location in program section 
$$FSR2 of the FSR. Its contents are specified by the current program through the .WFOWN 
routine. If not so specified, the file owner word contains 0. 


For nonprivileged users, the owner of a new file corresponds to the default UIC specification, 
as follows: 


e If the volume on which the new file is created is private (allocated), the owner UIC is the 
same as the UIC of the task creating the file. 


e If the volume on which the new file is created is a system volume, the owner UIC is the 
same as the task’s login UIC. 


For privileged users, the owner UIC is always the same as the UIC of the task creating the file. 


Note that for files created by privileged or nonprivileged tasks that are started by a time- 
scheduled request, the owner UIC is set to the UIC specified at task-build time. 


A specific UIC value can be stored in the file owner word by the .WFOWN routine (see 
Section 4.5.2). All new files then created and closed by your task will contain the specified UIC 
value. 


The format of the file owner word is shown in Figure 4-4. 
Figure 4-4: File Owner Word Format 


Bit 15 8 7 0 


ZK-5974 HC 


The routines for reading and writing the file owner word are described in Sections 4.5.1. and 
4.5.2. 


Note 


The UIC and the file protection word for the file (see Section 4.4) must not be 
set such that the UIC under which the task is running does not have access to 
the file. This condition results in a privilege violation. 
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_ When a file is created, the owner UIC is always set to either the UIC of the task creating the 
file or the task’s login UIC, as previously described. However, when closing the file, you can 
change the owner UIC by using the .WFOWN routine. If the file is not closed properly, the 
owner UIC will not change. 


4.5.1 .RROWN—Read $5FSR2 File Owner Word 


You use the .RFOWN routine to read the contents of the file owner word in program section 
$$FSR2. No registers need be preset before calling this routine. 


When called, the .RFOWN routine returns the following information: 


R1 Contains the file owner word (UIC). If the current program has not previously established 
the contents of the file owner word through the .WFOWN routine, R1 contains 0. 


4.5.2 .WFOWN—Write New SS$FSR2 File Owner Word 
You use the .WFOWN routine to initialize the file owner word in program section $$FSR2. 
You must preset the following register before calling this routine: 


R1 Must contain a file owner word to be written into $$FSR2. 


4.6 ASCII/Binary UIC Conversion Routines 


Your task calls the .ASCPP and .PPASC routines to convert a directory string from ASCII to 
binary or from binary to ASCII. 
4.6.1 .ASCPP—Convert ASCII Directory String to Equivalent Binary UIC 


Your task calls the .ASCPP routine to convert an ASCII directory string to its corresponding 
binary UIC. 


You must preset the following registers before calling this routine: 


R2 Must contain the address of the directory string descriptor in your program (see 
Chapter 2) for the string to be converted. 


R3 Must contain the address of a word location in your program to which the binary UIC 
is to be returned. The member number is stored in the low-order byte of the word, and 
the group number is stored in the high-order byte. 
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4.6.2 .PPASC—Convert UIC to ASCII Directory String 


Your task calls the .PPASC routine to convert a binary UIC to its corresponding ASCII directory 
string. 


You must preset the following registers before calling this routine: 


R2 Must contain the address of a storage area within your program into which you place the 
ASCII string. The resultant string can be up to 9 bytes in length, for example, [200,200]. 


R3 = Must contain the binary UIC value to be converted. The low-order byte of the register 
contains the member number, and the high-order byte of the register contains the group 
number. 


R4 = Must contain a control code. Bits 0 and 1 of this register indicate the following: 


Bit 0 Is set to 0 to suppress leading zeros (for example, 001 is returned as 1). Bit 0 
is set to 1 to indicate that leading zeros are not to be suppressed. 


Bit 1 Is set to 0 to place separators (square brackets and commas) in the directory 
string (for example, [10,20]). Bit 1 is set to 1 to suppress separators (for example, 
1020). 


The .PPASC routine adds to the contents of R2, allowing R2 to point to the byte immediately 
following the last byte in the converted directory string. 


4.7 Filename Block Routines 


FCS provides the .PARSE, .PRSDV, .PRSDI, .PRSFN, and .ASLUN routines, which perform 
functions related to a specified filename block. These routines are described in the following 
sections. FCS provides the main support for logical name translation in these routines. 


4.7.1 Logical Name Translation 


When FCS obtains a device name or a file specification, it examines the leftmost component 
to check for the presence of a logical name. FCS does this by checking whether the leftmost 
character string, which may consist only of alphanumeric characters, dollar signs ($), or 
underscores (_.), ends in either a colon (:) or a space. If it does, FCS recognizes the character 
string as a logical name and makes an attempt to translate the entire character string. If 
FCS finds an equivalence name, the original information that the logical name represents, the 
equivalence name is merged with the file specification without the logical name. If the leftmost 
character string ends in any character other than a space or colon, FCS uses the string as a file 
specification. 

In the following example, the first line shows how to specify a file specification. The second 
line shows the use of a logical name to specify the location of a file, as follows: 


$ TYPE ALPHA 

$ TYPE DISK: ALPHA 

In the first line, FCS obtains the file specification ALPHA and checks to see if ALPHA is a 
logical name because ALPHA is the leftmost (and in this example, the only) component of the 
file specification. In the second line, FCS checks to see if DISK, the leftmost component, is a 
logical name. FCS does not check ALPHA. 
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The system stores logical names in four logical name tables. When FCS translates logical names, 
it searches first the task table, then the session table, then the group table, and finally the system 
table. FCS uses the first match it finds. 


4.7.1.1 Iterative Translation 


When FCS translates logical names in file specifications, the logical name translation can be 
iterative. That is, after FCS translates a logical name in the file specification, it continues to 
translate and repeats the process of translating the file specification if it finds the presence of a 
logical name. 


Note 
Use the ASSIGN command for ail file-specification arguments. ASSIGN 
performs several checks to ensure that the logical names are syntactically correct. 


As an example of iterative translation, consider logical name table entries made with ASSIGN 
commands as follows: 


$ ASSIGN DB1: DISK 
$ ASSIGN DISK: [HUMIDO]WEATHER.SUM REPORT 


The first ASSIGN command equates the logical name DISK to the device DB1. The 
second ASSIGN command equates the logical name REPORT to the file specification 
DISK:[HUMIDO]WEATHER.SUM. In subsequent commands, or in programs you execute, you 
can refer to the logical name REPORT. For example: 


$ TYPE REPORT 


When FCS attempts to translate the logical name REPORT, it checks the logical name tables and 
finds the equivalence name DISK:[HUMIDO]WEATHER.SUM. It then checks the file specification 
for the presence of a logical name; if it finds a match in one of the logical name tables (DISK 
in this example), it translates that logical name also. When the logical name translation is 
complete, the following translated file specification results: 


DB1: [HUMIDO] WEATHER . SUM 


FCS limits logical name translation to 10 levels. If you define a logical name to more than 10 
levels or create a circular definition, an error occurs when you use the logical name. 


If a device name or file specification is preceded by an underscore, the logical translation process 
stops. In the following example, FCS would look for the file REPORT. in your default device 
and directory: 


TYPE _REPORT 


Note also that if an extension or version is included with the file name, the filename is not 
considered for logical translation. In the following example, FCS would look for the file 
REPORT.TXT in your default device and directory: 


TYPE REPORT .TXT 
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4.7.1.2 


Logical Translation Process 


The following three basic operations occur during the logical translation process: 


1, 


4.7.2. 


Parsing the file specification 


FCS determines the location and length of the various parts of the primary file specification. 
It sets flags indicating which parts were present and which parts contained wildcards. The 
length and location of the string following the file specification are also determined. 


Expanding the string 


FCS takes the first portion of the string and attempts to translate it. The first portion could 
be a logical name. A logical name can be a device name or a file name. If there is a logical 
name string to equivalent string translation, FCS uses the equivalent string as the secondary 
string in a merge. The primary string for this merge is the original file specification less the 
logical name. This operation is iterative until one of the following occurs: 


— There is no logical name to translate. 

- The translation fails. 

~ The result of the translation is not a file specification. 

~ The recursion limit of more than 10 levels of translation has occurred. 

~ The first character is an underscore. 

Merging the specifications 

FCS generates a merged string from the primary and the default string. The merged string 


consists of the primary string with any missing components filled in from the default string. 


PARSE—Fill in All File Name Information 


FCS includes the main support for logical name translation in the FCS directive PARSE. 
When the .PARSE routine receives a string, the .PARSE routine performs any necessary logical 
expansion and parses the resultant string. 


If you use logical name parsing, logical translation is performed first. If you have not requested 
logical name translation (as when it has already been done by CSI$4), the FL.AEX bit should 
be set in the F.FLG byte in the FDB. Setting this bit disables logical name translation. 


When called, the .PARSE routine first zeros the filename block pointed to by R1 and then stores 


the 


following information in the filename block: 
The ASCII device name (N.DVNM) 

The binary unit number (N.UNIT) 

The directory ID (N.DID) 

The Radix—50 file name (N.FNAM) 

The Radix—50 file type or extension (N.FTYP) 
The binary file version number (N.FVER) 
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For American National Standards Institute (ANSI) magnetic tape file names, the following 
information is stored in the filename block: 


¢ The ASCII device name (N.DVNM) 

¢ The binary unit number (N.UNIT) 

° The file name as 17 ASCII bytes (N.ANM1 and N.ANM2) 
¢ The binary file version number (N.FVER) 


In addition, the .PARSE routine calls the .ASLUN routine to assign the logical unit number 
(LUN) associated with the FDB to the device and unit currently specified in the filename block. 


Both formats for filename blocks are shown in detail in Appendix B. 


Before the .PARSE routine can be called, the FINIT$ macro (see Chapter 2) must be invoked 
explicitly in your program, or it must be invoked implicitly through a prior OPEN$x macro 
call. Note, however, that your task can issue the FINIT$ call only once in the initialization 
section of the program; that is, the FINIT$ operation must be performed only once per task 
execution. Furthermore, FORTRAN programs issue a FINIT$ call at the beginning of task 
execution; therefore, MACRO-11 routines used with the FORTRAN object time system must 
not issue a FINIT$ macro. 


You must preset the following registers before calling the .PARSE routine: 
RO  ~=Must contain the address of the desired FDB. 


R1 Must contain the address of the filename block to be filled in. This filename block is 
usually, but not necessarily, the filename block within the FDB specified in RO (that is, 
RO + F.FNB). 


R2 Must contain the address of the desired data-set descriptor if .PARSE is to access a 
data-set descriptor in filling in the specified filename block. This structure is usually, but 
not necessarily, the same as that associated with the FDB specified in RO (that is, the 
data-set descriptor pointed to by the address value in F.DSPT). 

If R2 contains 0, a data-set descriptor has not been defined; therefore, the data-set 
descriptor logic of the .PARSE routine is bypassed. 


R3 Must contain the address of the desired default filename block for the .PARSE routine 
to access a default filename block in filling in the specified filename block. This default 
filename block is usually, but not necessarily, the same as the one associated with the 
FDB specified in RO (that is, the default filename block pointed to by the address value 
in F.DFNB). 

If R3 contains 0, a default filename block has not been defined; therefore, the default 
filename block logic of the .PARSE routine is bypassed. 


Thus, RO and R1 each must contain the address of the appropriate data structure, while either R2 
or R3 must contain the address of the desired filename information. Both R2 and R3, however, 
may contain address values if the referenced structures both contain information required in 
filling in the specified filename block. 


The .PARSE routine fills in the specified filename block in the order described in the following 
sections. 
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4.7.2.1 Device and Unit Information 


The .PARSE routine first tries to fill in the filename block with device (N.DVNM) and unit 
(N.UNIT) information. The following operations are performed until the required information 
is obtained from the specified data structures: 


1. If the address of a data-set descriptor is specified in R2 and the data-set descriptor contains 
a device string, the .PARSE routine moves the device and unit information from the data-set 
descriptor into the specified filename block. 


2. If step 1 fails, and if the address of a default filename block is specified in R3, and the 
default filename block contains a nonzero value in the device name field, the .PARSE 
routine moves the device and unit information from the device name field into the specified 
filename block. 


3. If step 2 fails, the PARSE routine uses the device and unit currently assigned to the LUN 
in offset location F.LUN of the specified File Descriptor Block (FDB) to fill in the filename 
block. 


This feature allows a program to use preassigned logical units that are assigned through 
either the device assignment (ASG) option of the Task Builder (TKB) or one of the following 
commands: ASSIGN in the DIGITAL Command Language (DCL) or ASN in the Monitor 
Console Routine (MCR). In this case, you simply avoid specifying the device string in the 
data-set descriptor and the device name in the default filename block. 


4. If the LUN in F.LUN is currently unassigned, the .PARSE routine assigns this number to 
the system device (SY0). 


The .PARSE routine first determines the device and unit, assigns the LUN, and then invokes 
the GLUN$ directive to obtain necessary device information. The required information obtained 
by GLUN$ is placed by the .PARSE routine into the following offsets in the filename block 
pointed to by R1: 


N.DVNM __ Device Name Field. This field contains the redirected device name. 
N.UNIT Unit Number Field. This field contains the redirected unit number. 


Additionally, the .PARSE routine places the information returned by GLUNS$ into the following 
offsets in the FDB, which RO points to: 


F.RCTL Device Characteristics Byte. This cell contains device-dependent information from 
the first byte of the third word returned by the GLUN$ directive. The bit definitions 
pertaining to the device characteristics byte are described in detail in Appendix A. 
If desired, you can examine this cell in the FDB to determine the characteristics of 
the device associated with the assigned LUN. 


F.VBSZ Device Buffer Size Word. This location contains the information from the sixth 
word returned by the GLUN$ directive. The value in this cell defines the device 
buffer size (in bytes) of the device associated with the assigned LUN. 


The GLUN$ directive is described in detail in the RSX-11M-PLUS and Micro/RSX Executive 
Reference Manual. 
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4.7.2.2 Directory Identification Information 
The N.DID field in the filename block contains the following information: 


Word Meaning 


1 File ID 
2 File sequence number 
3 Reserved 


The .PARSE routine moves these three words from the Master File Directory (MFD) to the 
N.DID field in the filename block. The file ID is the header number of the header (in the index 
file) for a User File Directory (UFD). The .FIND routine uses the file ID to locate and search a 
UFD and to fill in the N.FID field in the filename block. The N.FID has the same format as the 
N.DID field except that it identifies the header number of the header for a user data file. The 
file sequence number is incremented each time a file header is reused for a new file. 


Following the operations described in the preceding section, .PARSE attempts to fill in the 
filename block with directory identification (N.DID) information. The methods for obtaining 
this information are as follows: 


1. If your task specifies the address of a data-set descriptor in R2 and the data-set descriptor 
contains a directory string, File Control Services (FCS) uses that directory string to find the 
associated UFD in the MFD. The resulting file ID is then moved into the directory-ID field 
of the specified filename block. 


2. If step 1 fails, and your task specifies the address of a default filename block in R3, and the 
default filename block contains a nonzero directory ID, the contents of the default filename 
block are moved into the specified filename block. 


Because none of the parameters of the NMBLK§$ macro call (see Chapter 2) initialize the 
three words starting at offset location N.DID in the default filename block, your task must 
initialize these cells manually. Or your task can call the .GTDIR routine (see Section 4.9.1) 
or the .GTDID routine (see Section 4.9.2). Note that these routines can also initialize a 
specified filename block directly with required directory information. 


3. If neither step 1 nor step 2 yields the required directory string, the .PARSE routine examines 
the default directory string words in program section $$FSR2. If your program has previously 
initialized these words through use of the .WDFDR routine, FCS uses the string described 
as the default directory. 


4. If steps 1 to 3 fail to produce directory information, FCS uses the binary value stored in the 
default UIC word in program section $$FSR2 as the directory identifier. Unless changed 
by you through the .WDFUI routine, this word contains the UIC under which the task is 
running. 


Note 


The .PARSE routine does not accept UICs that contain wildcards. Additionally, 
the .PARSE routine does not set filename block status word (N.STAT) bits 
NB.SD1 or NB.SD2 (group and owner wildcard specifications, respectively). 
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4.7.2.3 File Name, File Type, and File Version Information 


After completing the operations described in the preceding section, the .PARSE routine attempts 
to obtain file name information (N.FNAM, N.FTYP, and N.FVER), as follows: 


1. If your task specifies the address of a data-set descriptor in R2 and this structure contains 
a filename string, the file name information therein is moved into the specified filename 
block. 


2. If your task specifies the address of a default filename block in R3, and one or more of 
the file name, file type, and file version number fields of the data-set descriptor that you 
specified in R2 are null, the corresponding fields of the default filename block fill in the 
specified filename block. 


3. If neither step 1 nor step 2 yields the requisite file name information, any specific fields not 
available from either source remain null. 


Note 
If a period (.) appears in the filename string without an accompanying file type 


designation (for example, TEST. or TEST.;3), FCS interprets the file type as 
being explicitly null. In this case, the default file type is not used. 


Similarly, if a semicolon (;) appears in the filename string without an 
accompanying file version number (for example, TEST.DAT;), FCS also interprets 
the file version number as being null; again, the default file version number is 
not used. This information concerning semicolons in filename strings does not 
apply to the 17-byte ASCII filename strings supported for ANSI magnetic tape. 


4.7.2.4 Using the FDB Extension for Logical Names 


FCS uses the FDB extension to obtain the correct directory string. The extension has the 
following format: 


BYTE Extension length 

BYTE Unused 

.BYTE Length of the directory string buffer 

BYTE Length of the directory string (filled in by .PRSDI) 
.WORD _ Address of the directory string buffer 


The FDB extension block and the directory string buffer are allocated in your task’s address 
space. You fill in the address, the length of the buffer, and the length of the extension into the 
appropriate locations in the FDB extension block. You then place the address of the extension 
block in the offset F.EXT in the FDB. When the directory parsing code detects that F.EXT has 
a value, it uses the value as an address and moves the directory string into the buffer. It 
also puts the length of the actual directory string into the appropriate byte of the extension. 
This directory string is always filled in, unless FCS obtains the directory from the default name 
block, because the default name block does not contain the directory string. If FCS obtains the 
directory from the default name block, FCS sets the directory length to zero. 
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4.7.2.5 Other Filename Block Information 


After performing all the previously described operations, the .PARSE routine also fills in the 
status word (offset location N.STAT) of the filename block specified in R1. 


The bit definitions for this word are presented in Appendix B. Note that in Appendix B, 
Table B-2 the directory, device, file name, file type, or file version number specification pertains 
to ASCII data supplied through the data-set descriptor pointed to by R2. 


In addition, the .PARSE routine zeros offset location N.NEXT in the filename block pointed to 
by R1. This action has implications for wildcard operations, as described in Section 4.8.1. 


4.7.2.6 .EXPLG Module (Expand Logical) 


The .EXPLG module expands a logical name and returns a pointer to the task that points to the 
expanded string. The module has the following inputs and outputs: 


Inputs R2—Pointer to the data-set descriptor of the string to be expanded. 


Outputs R2—Pointer to the data-set descriptor of the expanded string. All other registers 
are preserved. 


This routine expands the string into the same buffer that the .PARSE routine and CSI$4 use 
for input files; therefore, caution is advised if you use this method. In addition, the call only 
accepts logical names that expand into a correct FCS file specification. The inclusion of a node 
specifier or other non-FCS characters results in an error being returned. 


4.7.3 .PRSDV—Fill in Device and Unit Information Only 


The .PRSDV routine is identical to the .PARSE routine, except that it performs only those 
operations associated with requisite device and unit information (see Section 4.7.1.1). The 
-PRSDV routine zeros the filename block pointed to by R1, calls the .PARSE routine to operate 
on the device and unit fields in the specified data-set descriptor or default filename block, and 
assigns the LUN contained in offset location F.LUN of the specified FDB. 


After the logical device translation is performed, .PRSDV fills the filename block with the 
required device and unit information. If the device is LB, the actual physical device name 
and unit are placed in the filename block. If the logical device expands to contain anything 
other than a device specification, for example, a directory or a filename, the remainder is 
ignored. Setting the FL.AEX bit (see Chapter 6) disables logical expansion for the device and 
unit information. 


4.7.4 .PRSDI—Fill in Directory Identification Information Only 


The .PRSDI routine is identical to the .PARSE routine, except that it performs only those 
operations associated with requisite directory identification information (see Section 4.7.1.2). 
The .PRSDI routine performs a .PARSE operation on the directory identification information 
(N.DID) field in the specified data-set descriptor or default filename block. The .PRSDI routine 
does not perform any logical name expansion. 
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4.7.5 .PRSFN—Fill in File Name, File Type, and File Version Only 


The .PRSEN routine is identical to the PARSE routine, except that it performs only those 
operations associated with requisite file name, file type, and file version information (see 
Section 4.7.2.3). This routine performs a .PARSE operation on the file name, file type, and file 
version information fields (N.FNAM, N.FTYP, N.FVER) in the specified data-set descriptor or 
default filename block. The .PRSFN routine does not perform any logical name expansion. 


4.7.6 .ASLUN—Assign LUN 


The .ASLUN routine assigns a logical unit number (LUN) to a specified device and unit and 
returns the device information to a specified FDB and filename block. 


You must preset the following registers before calling this routine: 
RO Must contain the address of the desired FDB. 


R1 Must contain the address of the filename block where the desired device and unit 
information are located. This filename block is usually, but not necessarily, within the 
FDB specified by the address in RO. 


If the device name field (offset location N.DVNM) of the filename block pointed to by Rl 
contains a nonzero value, the specified device and unit are assigned to the LUN contained in 
offset location F.LUN in the FDB pointed to by RO. 


If offset location N.DVNM in the filename block contains 0, then the device and unit currently 
assigned to the specified LUN are returned to the appropriate fields of the filename block. 


Finally, if the specified LUN is not assigned to a specific device, the .ASLUN routine assigns it 
to the system device (SY0) by default. 


The information returned to the specified filename block and the specified FDB is identical to 
that returned by the device and unit logic of the .PARSE routine (see Section 4.7.1.1). 


4.8 Directory Entry Routines 


4.8. 


The .FIND, ENTER, and .REMOV routines find, insert, and delete directory entries. The term 
“directory entry” refers to entries in both the MFD and the UFD. 
1 .FIND—Locate Directory Entry 


You call the .FIND routine to locate a directory entry by file name and to fill in the file 
identification field (N.FID) of a specified filename block. 


You must preset the following registers before calling this routine: 
RO Must contain the address of the desired FDB. 


Rl Must contain the address of a filename block. This filename block is usually, but not 
necessarily, within the FDB specified by the address in RO. 


When invoked, the .FIND routine searches the directory file specified by the directory-ID field 
of the filename block. This file is searched for an entry that matches the specified file name, 
file type, and file version number. Two special file versions are defined as follows: 


® Version 0 is matched by the latest (largest) version number encountered in the directory 
file. 
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e Version -1 is matched by the oldest (smallest) version number encountered in the directory 
file. 


If either of these special versions is specified in the filename block, the matching version number 
is returned to the filename block. In this way, the actual version number is made available to 
the program. 


Certain wildcard operations require the use of the .FIND routine. Three bits in the filename 
block status word (see N.STAT in Appendix B, Table B-2) indicate whether a wildcard (*) was 
specified for a file name, a file type, or a file version number field. If the wildcard bit in N.STAT 
is set for a given field, any directory entry matches that corresponding field. Thus, if the file 
name and file version number fields contain wildcard specifications (*), and the file type field 
is specified as .OBJ (that is, *.OBJ;*), the first directory entry encountered that contains .OBJ in 
the file type field matches. 


When a wildcard match is found, the complete file name, file type, and file version number 
fields of the matching entry are returned to the filename block, along with the file-ID field 
(N.FID). Thus, the program can determine the actual name of the file just found. Offset location 
N.NEXT in the filename block is also set to indicate where that directory entry was found in 
the directory file. FCS uses this information in subsequent .FIND operations to locate the next 
matching entry in the directory file. 


For example, the .FIND routine often opens a series of files when wildcard specifications are 
used. The following operations are typical: 


1. Call the .PARSE routine. This routine zeros offset location N.NEXT in the filename block 
in preparation for the iterative .FIND operations described in step 3. 


2. Check for wildcard bits set by the .PARSE routine in the filename block status word (see 
N.STAT in Appendix B, Table B-2). An instruction sequence such as that shown in the 
following text tests for the setting of wildcard bits in N.STAT: 


BIT #NB.SVR!NB.STP!NB.SNM,N.STAT(R1) 
BEQ  NOWILD ;BRANCH IF NOT SET. 


3. If wildcard specifications are present in the filename block status word, repeat the following 
sequence until all the desired wildcard files have been processed: 


CALL .FIND 

BCS DONE ;ERROR CODE IE.NSF INDICATES 
;NORMAL TERMINATION. 

OPEN$ RO 


Wildcard .FIND operations update offset location N.NEXT in the filename block. In essence, 
the contents of this cell provide the necessary information for continuing the directory file 
search for a matching entry. 


4. Perform the desired operations on the file. 
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Note 
This procedure applies only to the following types of wildcard file specifications: 


TEST . DAT; * 
TEST. *;* 
* DAT ;* 
TEST. *;5 
* .DAT;3 


This procedure does not work for the following types of wildcard file 
specifications: 


* .DAT 
TEST. * 


In summary, if a wildcard file specification is present in either the file name field or the file type 
field, the file version number field must also contain either an explicit wildcard specification (*) 
or a specific file version number. In the latter case, however, the version number cannot be 0, 
for the latest version of the file, or -1, for the oldest version of the file. 


When your task sets NB.ANS, the .FIND operation compares the file name against the full 
17-character ANSI filename string that is stored in the filename block (see Appendix B). When 
NB.ANS is clear, the file name is converted to Radix—50 format, as described in Appendix C. 


ANSI magnetic tape file names in the following formats can be converted to Radix—50 format: 
¢ Up to nine Radix-50 characters followed by spaces 


* Up to nine Radix-50 characters followed by a period, followed by spaces, or followed by a 
3-character file type 


Note that unless NB.ANS is set before the call to .FIND, some file names may be incorrectly 
matched. For example, the names “ABC” and “ABC.” are considered the same when compared 
with the name ABC in Radix—-50 format. 


When a wildcard operation is performed, the name returned in the filename block is normally 
converted to Radix-50 format. However, if NB.ANS is set, the ANSI filename string is returned 
as up-to-17 ASCII bytes. The first 12 bytes are returned at offset N.ANM1 in the ANSI filename 
block. The remainder are returned at offset N.ANM2. 


It is incorrect to set NB.ANS before a wildcard .FIND operation unless both file name and file 
type are wild, or neither file name nor file type are wild. 


To delete a file whose file descriptor entry in the FDB contains wildcards, you must save the 
values in the fields N.STAT and N.NEXT in the FDB, and then zero these fields in the FDB. A 
DELETE call then uses the information returned from the last .FIND to delete the file. Once 
the file is deleted, the saved values of N.STAT and N.NEXT must be restored in the FDB. 
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4.8.2 .ENTER—Insert Directory Entry 
You use the .ENTER routine to insert an entry by file name into a directory. 
You must preset the following registers before calling this routine: 
RO Must contain the address of the desired FDB. 


R1 Must contain the address of a filename block. This filename block is usually, but not 
necessarily, the filename block within the FDB specified in RO. 


If the file version number field of the filename block contains 0, indicating a default version 
number, the ENTER routine scans the entire directory file to determine the current highest 
version number for the file. If a version number for the file is found, this entry is incremented 
to the next higher version number; otherwise, it is set to 1. The resulting version number is 
returned to the filename block, making this number known to the program. 

Note 


Wildcard specifications cannot be used in connection with ENTER operations. 


4.8.3 .REMOV—Delete Directory Entry 


You use the .REMOV routine to delete an entry from a directory by file name. This routine 
deletes only a specified directory entry; it does not delete the associated file. 


You must preset the following registers before calling this routine: 
RO = Must contain the address of the desired FDB. 


R1 = Must contain the address of a filename block. This filename block is usually, but not 
necessarily, the filename block within the FDB specified in RO. 


Wildcard specifications operate in the same manner as those defined for the .FIND routine 
described in Section 4.8.1. The file version number for .REMOV operations must be an explicit 
number (including 0 and -1) or a wildcard. Each .REMOV operation deletes the next directory 
entry that has the specified file name, file type, and file version number. 


4.9 Filename Block Routines 


The .GTDIR and .GTDID routines insert directory information in a specified filename block. 
Sections 4.9.1 and 4.9.2 describe the use and operation of these routines. 


4.9.1 .GIDIR—Insert Directory Information in Filename Block 


You call the .GTDIR routine to insert directory information from a directory string descriptor 
into a specified filename block. 
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You must preset the following registers before calling this routine: 
RO Must contain the address of the desired FDB. 


R1 Must contain the address of the filename block in which the directory information is to 
be placed. This filename block is usually, but not necessarily, within the FDB specified 
by the address in RO. 


R2 Must contain the address of the 2-word directory string descriptor in your program. This 
string descriptor defines the size and the address of the desired directory string. 


This routine performs a .FIND operation for the specified UFD in the MFD and returns the 
resulting directory ID to the three words of the specified filename block, starting at offset location 
N.DID. The .GTDIR routine preserves the information in offset locations N.FNAM, N.FYTP, 
N.FVER, N.DVNM, and N.UNIT of the filename block, but the routine clears the rest of the 
filename block. 


You can also use the .GTDIR routine with the NMBLK$ macro call (see Chapter 2) to insert 
directory information into a specified default filename block. 


4.9.2 .GTDID—Insert Default Directory Information in Filename Block 


The .GTDID routine provides an alternative means for inserting directory information into a 
specified filename block. Instead of allowing the specification of the directory string, as does the 
GTDIR routine, this routine uses the binary value found in the default UIC word maintained 
in program section $$FSR2 as the desired UFD. 


You must preset the following registers before calling the .GTDID routine: 
RO Must contain the address of the desired FDB. 


R1 Must contain the address of a filename block in which the directory information is to be 
placed. This filename block is usually, but not necessarily, within the FDB specified by 
the address in RO. 


When called, the .GTDID routine takes the default UIC from its 1-word location in program 
section $$FSR2 and performs a .FIND operation for the associated UFD in the MFD. The 
resulting directory ID is returned to the three words of the specified filename block, starting at 
offset location N.DID. As does the .GTDIR routine, .GTDID preserves offset locations N.FNAM, 
N.FTYP, N.FVER, N.DVNM, and N.UNIT in the filename block, but .GTDID clears the rest of 
the filename block. 


The .GTDID routine uses considerably less code than the .GTDIR routine. Its input is the binary 
representation of a UIC rather than an ASCII string descriptor. Therefore, it does not invoke 
the .PARSE logic; furthermore, .GTDID is specifically for use in programs that open files by 
using the OFNB$ macro call (see Chapter 3). Such a program does not invoke the .PARSE 
logic because all necessary file name information is provided to the program in filename block 
format. 


Like the .GTDIR routine described in Section 4.9.1, the .GTDID routine can be used with the 
NMBLK$ macro call (see Chapter 2) to insert directory information (N.DID) into a specified 
default filename block. You also have the option to initialize offset location N.DID manually 
with the required directory information. 


The .GTDID routine returns file-ID 177777,177777,0 for nondirectory devices such as terminals. 
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4.10 File Pointer Routines 
The .POINT, .POSRC, .MARK, and .POSIT routines point to a byte or a record within a specified 
file. Sections 4.10.1 to 4.10.4 briefly describe the use of these routines and their operation. 
4.10.1 .POINT—Position File to Specified Byte 


You call the .POINT routine to position a file pointer to a specified byte in a specified virtual 
block. If locate mode is in effect for record I/O operations, the .POINT routine also updates the 
value in offset location F.NRBD+2 in the associated FDB in preparation for a PUT$ operation in 
locate mode. 


You must preset the following registers before calling this routine: 

RO Must contain the address of the desired FDB. 

R1 ~—- Must contain the high-order bits of the virtual block number. 

R2 ~~ Must contain the low-order bits of the virtual block number. 

R3 Must contain the desired byte number within the specified virtual block. 


For a description of virtual block numbers and how these 2-word values are formed, refer to 
Chapter 2. 


Note 


Use of the .POINT routine is restricted to files accessed with GET$ or PUT$ 
macros. For files accessed with READ$ or WRITE$ macros, use the FDBK$R 
macro to initialize the block access section of the FDB. 


The .POINT routine is used often with the .MARK routine and achieves a limited degree of 
random access with variable-length records. The .MARK routine saves the positional information 
of a file, permitting you to temporarily close that file and to reopen it later at the same position; 
this procedure is outlined in the following steps: 


1. Call the .MARK routine to save the current positional context of the file. 
Close the file. 


2 

3. Reopen the file when desired. 

4. Load the information returned by the .MARK routine into R1, R2, and R3. 
5 


Call the .POINT routine. The .POINT routine may be called to rewind a file on disk or 
ANSI magnetic tape to its start. For this case, R1 and R3 must be set to 0, and R2 must be 
set to 1. The .POINT routine may also be called to rewind a file that is open on a terminal. 
Doing so clears the terminal end-of-file condition. 


6. Resume processing of the file. 
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4.10.2 .POSRC—Position File to Specified Record 


The .POSRC routine sets up the position information for a file to a specified fixed-length record 
within a file. If locate mode is in effect for record I/O operations, the .POSRC routine also 
updates the value in offset location F.NRBD+2 in the associated FDB in preparation for a PUT$ 
operation in locate mode. 


Before calling this routine, you must set offset locations F.RCNM+2 and F.RCNM in the FDB to 
the desired record number and ensure that the correct record size is reflected in offset location 
F.RSIZ of the FDB. 


The following register must be preset before calling the .POSRC routine: 
RO Must contain the address of the associated FDB. 


You use the .POSRC routine when performing random access PUT$ operations in locate mode. 
Normally, PUT$ operations in locate mode are sequential; however, when you use random 
access mode, you must follow the next procedure to ensure that the record is built at the desired 
location: 


1. Set offset locations F.RCNM+2 and F.RCNM in the associated File Descriptor Block (FDB) 
to the desired record number. 


2. Call the .POSRC routine. 


3. Build the new record at the address returned (by the .POSRC call) in offset location 
F.NRBD+2 of the associated FDB. 


4. Perform the PUT$ operation. 


4.10.3 .MARK—Save Position Information Context of File 


The .MARK routine allows you to save the current position information of a file for later use; 
you can save the current position information of a file, close that file, and later reopen the file 
to the same position. The .MARK routine also allows you to alter records within a file; you 
can save the file position, retrieve information elsewhere in that file, and return to the saved 
position of the file to alter the desired record. This sequence may be repeated to update any 
number of desired records in the file. 


You must preset the following register before calling the .MARK routine: 

RO Must contain the address of the associated FDB before calling this routine. 
When called, the .MARK routine returns information to the following registers: 
R1 Contains the high-order bits of the virtual block number. 

R2 Contains the low-order bits of the virtual block number. 

R3 ‘Contains the number of the next byte within the virtual block. 


R3 points to the next byte in the block. For example, if four GET$ operations are performed, 
followed by a call to the MARK routine, R3 points to the first byte in the fifth record in the 
file. 
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4.10.4 .POSIT—Return Specified Record Position Information 


The .POSIT routine calculates the virtual block number and the byte number locating the 
beginning of a specified record. 


The following register must be preset before calling this routine: 
RO = Must contain the address of the associated FDB. 


In addition, offset locations F.RCNM and F.RCNM+2 in the associated FDB must contain the 
desired record number. 


Unlike the .POSRC routine, which sets up the position information of the file to the specified 
record, .POSIT calculates the positional information of a specified record so that a .POINT 
operation can be performed later to position to the desired record. 


The .POSIT routine returns register values identical to those described previously for the .MARK 
routine. 


4.11 .XQlIO—Queue 1|/O Function Routine 


The Queue I/O Function Routine (.XQIO) executes a specified QIO$ function and waits for its 
completion. 


You must preset the following registers before calling this routine: 
RO Must contain the address of the desired FDB. 


R1 Must contain the desired QIO$ macro function code. Refer to the RSX-11M-PLUS and 
Micro/RSX I/O Drivers Reference Manual for the desired QIO$ macro function codes. 


R2 = Must contain the number of optional parameters, if any, to be included in the QIO$ 
directive. 


R3 Must contain the beginning address of the list of optional QIO$ directive parameters, if 
R2 contains a nonzero value. Refer to the RSX-11M-PLUS and Micro/RSX I/O Drivers 
Reference Manual for the parameter list. 


4.12 .RENAM—Rename File Routine 


The .RENAM routine is called to change the name of a file in its associated directory. To 
rename a file, you must specify the address of an FDB containing file name information, a LUN, 
and an event flag number. 


If the file to be renamed is open when the call to .RENAM is issued, that file is closed before 
the renaming operation is attempted. 


You must preset the following registers before calling this routine: 
RO = Must contain the address of the FDB associated with the file with the original name. 


R1 = Must contain the address of the FDB containing the desired file name information, the 
LUN assignment, and the event flag. 


If the renaming operation is successful, a new directory entry is created and the original entry 
is deleted. If the operation is unsuccessful, the file is closed under its original name, and the 
associated directory is not affected. 


File Control Routines 4-23 


The RENAM routine uses the absence of a value in location F.FNB + N.FID to indicate that 
PARSE must be called to parse a file specification (an open file always has a nonzero value in 
F.FNB + N.FID). If neither a data-set descriptor nor a default filename block is present, .PARSE 
returns a null file name. The rename operation then produces a new file name of version *.;1.” 
If a wildcard (*) is part of the input file specification, wildcard processing like that described 
for the FIND routine occurs. Wildcards are not allowed in an output file specification. 


Note 


The renaming process is merely a directory operation that replaces an old entry with a new 
entry. The file name stored in the file header block is not altered. 


4.13 .EXTND—File Extension Routine 


The .EXTND routine extends either contiguous or noncontiguous files. The file to be extended 
can be either open or closed. A call to the .EXTND routine disables file truncation. You must 
explicitly call .TRNCL to truncate a file after you call EXTND. 


You must preset the following registers before calling the .EXTEND routine: 
RO Must contain the address of the associated FDB. 
R1 Must contain a numeric value specifying the number of blocks to be added to the file. 


R2 Must contain the extension control bits, as appropriate. The possible bit configurations 
for controlling file-extend operations are detailed in Table 4-1. This table defines the bits 
in the low-order byte of R2. The high-order 8 bits of R2 (bits 8 to 15) are used with the 
16 bits of R1 to define the number of blocks to be added to the file (see Note 1, which 
follows). 


Notes 


1. FCS uses the contents of R1 and the high-order byte of R2 (bits 8 to 15) 
to perform the specified .EXTND operation. Thus, 24 bits of magnitude 
are available for specifying the number of blocks by which the file is to be 
extended. 


2. If a file previously had space allocated to it, a contiguous file extension by 
the EXTND routine cannot be done. You can create a contiguous file by 
opening a new file with a zero allocation and by calling .EXTND to allocate 
the desired number of blocks. 


3. When writing a new file using QIO$ macros, the task must explicitly issue 
EXTND calls, as necessary, to reserve enough blocks for the file, or the 
file must be initially created with sufficient blocks. In addition, the task 
must put an appropriate value in the FDB for the end-of-file block number 
(F.EFBK) before closing the file or rewinding and reading it. 


4. If R2 contains 0, FCS defaults to noncontiguous allocation. 


4-24 File Control Routines 


In general, when FCS implicitly extends a file, it activates file truncation. See Section 4.14 for 
information on how to turn off file truncation. When your program explicitly allocates space to 
a file, either with an OPEN$ or .EXTND, FCS turns off truncation. To turn off file truncation 
and close the file, call the following routines: 


1. Call the EXTND routine. Set both R1 and R2 to 0. 
2. Issue the CLOSE$ macro. 


Table 4-1: R2 Control Bits for .EXTND Routine 
Value in Low-Order 


Byte of R2 Meaning 
0 Indicates that the file extent is to be noncontiguous. 
200 Indicates that the file extent is to be noncontiguous. This clears the 


contiguous file attribute. 


201 Indicates that the contiguous area is to be added to the file. This 
clears the contiguous file attribute. 


203 Indicates that the largest available contiguous area is to be added to 
the file if the desired file extent space is not available. This clears the 
contiguous file attribute. 


205 Indicates that this is the initial extent of the file. The file is to be 
contiguous. 
207 Indicates that the largest contiguous area up to the specified extend 


size is to be added to the file. The file is to be contiguous. 


210 Indicates that the file is to be extended by the default extend size for 
the volume. The extend is to be noncontiguous. 


211 Indicates that the file is to be extended by the default extend size for 
the volume. The extend is to be contiguous; whereas, the file is to 
be noncontiguous. 


4.14 .TRNCL—File Truncation Routine 


The .TRNCL routine truncates a file to the logical end of the file, deallocates any space beyond 
this point, and closes the file. 


The following register must be preset before calling this routine: 
RO = Must contain the address of the associated FDB. 


The file must have been opened with both write and extend access privileges. Otherwise, the 
truncation will fail. 


The close operation will be attempted even if the truncation operation fails. If errors occur in 
both operations, the error code from the close operation will be returned. 


FCS turns on truncation when it extends a file. However, when your program explicitly calls 
the .EXTND routine, FCS turns off truncation. 
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4.15 File Deletion Routines 
FCS provides the .MRKDL and .DLFNB routines for deleting files. 


Note 


If you use the .MRKDL or .DLFNB routine to delete a file containing sensitive 
information, you should clear the file before closing it or reformat the disk to 
destroy the sensitive information. (Although the file is marked for deletion, the 
information physically remains on the volume until written over with another 
file, and this information could be analyzed by unauthorized users.) 


4.15.1 .MRKDL—Mark Temporary File for Deletion 


You use the .MRKDL routine to mark a temporary file for deletion—that is, a file created 
through the OPNT$W macro call (see Chapter 3). Such a file has no associated directory entry. 


A call to the .MRKDL routine is issued prior to closing a temporary file. The file so marked is 
then deleted when the file is closed. 


You must preset the following register before calling the .MRKDL routine: 


RO Must contain the address of the associated FDB. This FDB is assumed to contain the file 
identification, device name, and unit information of the file to be deleted. 


If the .MRKDL routine is invoked while the temporary file is open, as is normally done, the 
file is deleted unconditionally when it is closed. This occurs even if the calling task terminates 
abnormally without closing the file. 


4.15.2 .DLFNB—Delete File by Filename Block 


You use this routine to delete a file by filename block. The .DLFNB routine assumes that the 
filename block is completely filled; when called, it closes the file, if necessary, and then deletes 
the file. 


You must preset the following register before calling the .DLFNB routine: 
RO Must contain the address of the associated FDB. 


The .DLFNB routine operates in the same manner as the DELET$ macro call (see Chapter 3), 
but .DLENB does not require any of the PARSE logic and thus requires less memory than the 
normal DELET$ function. 


Like the DELET$ operation, however, the .DLFNB operation fails if the file to be deleted is 
not open, and if an explicit file version number is missing from offset location N.FVER of the 
associated filename block. 
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4.16 .CTRL—Device Control Routine 


You call the .CTRL routine to perform device-specific control functions. The following are 
examples of .CTRL device-specific functions: 


¢ Rewind a magnetic tape volume set. 

* Position to the logical end of a‘magnetic tape volume set. 

e Close the current magnetic tape volume and continue file operations on the next volume. 
* Space forward or backward n blocks on a magnetic tape. 

* Rewind a file on a magnetic tape or a terminal (record-oriented device). 

¢ Clear the terminal end-of-file. 


You must preset the following registers before calling this routine to perform the first three 
bulleted items listed previously in this section. 


RO = Must contain the address of the associated FDB. 
Rl Must contain one of the following function codes: 
¢ FF.RWD rewinds a magnetic tape volume set. 
¢ FF.POE positions to the logical end of a magnetic tape volume set. 
e FF.NV closes the current volume and continues file operations on the next volume of 
a magnetic tape volume set. 
R2 Must be set to 0. 
R3 Must be set to 0. 


When using .CTRL to space forward or backward, you must ensure that registers RO, R1, R2, 
and R3 contain the following values: 


RO Must contain the address of the associated FDB. 
R1 Must contain the value FF.SPC. 


R2 = Must contain the number of blocks to space forward or backward. A positive number 
means space forward; a negative number means space backward. 


R3 Must contain 0. 


When using .CTRL to rewind a file, you must ensure that register R1 contains the value FF.RWF 
and that registers R2 and R3 contain 0. 


See Chapter 5 for an explanation of using .CTRL to accomplish magnetic tape device-specific 
functions. 
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4.17 .FLUSH—Buffer Flush Routine 


The buffer flush routine (.FLUSH) writes the block buffer to the file being written in record mode. 
The .FLUSH routine also writes file attributes (including F.EFBK and F.HIBK, the end-of-file and 
high-allocation block numbers) each time the routine is called. 


Closing the file guarantees that the block buffer is flushed and that the file attributes will be 
written back to the file header. However, closing and opening a file frequently, solely to write 
the block buffer, causes high system overhead and unnecessary disk accesses. 


4.17.1 Purpose of the .FLUSH Routine 


When FCS executes a PUT$ macro to a disk file, the PUT$ macro puts a record into the block 
buffer. When the block buffer is full, or the file is closed, FCS writes the block buffer to the 
file. You cannot predict when FCS will actually write the block buffer to the file. 


Some applications may require that a record be written to a file immediately. As an example, 
a task that handles a laboratory device may write small amounts of data to a file every few 
minutes. If the system crashes, the contents of the block buffer may not have been written to 
the file. This data may be lost unless a PUT$ is immediately followed by a call to the .FLUSH 
routine. As another example, the .FLUSH routine should be called by an originating task to 
write data immediately if another task must then read data written by that originating task. In 
these examples, the tasks need not close the file to ensure that the data is written to the file. 


4.17.2 When .FLUSH Should Be Used 
Your task should call .FLUSH whenever data should be immediately written to a file. 


You need not call the .FLUSH routine for block mode (WRITE$) or record mode (PUT$) write 
operations to a record-oriented device; the block buffer is always written in these cases. Nothing 
happens if you call .FLUSH when a file is open under these circumstances except the return of 
a cleared Carry bit and status +1 (success) in FDB byte F.ERR. 

4.17.3 Performance Considerations Using .FLUSH 


Calling the .FLUSH routine after every PUT$ macro can greatly increase I/O activity compared 
to using solely the PUT$ macro. One alternative is to call the .FLUSH routine after certain 
intervals have passed or after a certain number of calls to PUTS. 


4.17.4 Using the .FLUSH Routine 
You must preset the following register before calling this routine: 
RO Must contain the address of the associated FDB. 


During output, all registers are preserved, the Carry bit is clear or set to indicate success or 
failure, and the FDB F.ERR byte contains the success or failure code. 
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Chapter 5 
File Structures 


This chapter describes the structure of files supported by the RSX-11 systems. Specifically, 
this chapter covers the identical file structure that exists on disk, DECtape, and DECtape II. In 
addition, it also describes the American National Standards Institute (ANSI) file structure on 
magnetic tape supported by the RSX-11M-PLUS and Micro/RSX systems. 


The disk, DECtape, and DECtape II file structure is called Files—11; the magnetic tape file 
structure is ANSI standard. 


The Files-11 structure is a file-organization system, which primarily determines the way that 
files and their associated control files are arranged on a disk or DECtape. Associated with the 
Files—11 structure is a system of data structures in memory, the most important of which include 
the Volume Control Block (VCB), the File Control Block (FCB), and the Device Control Block 
(DCB). Files—11 structure includes not only the physical file and its associated control files, but 
it also includes the necessary information in these files that determines the file’s size, location, 
content, and various attributes. 


The ANSI standard describes a way of organizing sequential files on a magnetic tape that allows 
the tape to be used on any computer system. The standard includes file structure, labeling, and 
physical characteristics such as end-of-tape length. 


5.1 Disk and DECtape File Structure (Files—11) 


Disk and DECtape volumes (defined by and associated with a VCB) contain both user files 
and system files. Disks and DECtapes initialized using the Monitor Console Routine (MCR) 
command INITVOLUME or the Digital Command Language (DCL) command INITIALIZE have 
the standard Files—11 structure built for them. The standard system files created by these 
commands include the following: 


e Index file 
¢ Storage allocation file 
e Bad block file 
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5.1. 


¢ Master File Directory (MFD) 
¢ Checkpoint file 


Each Files-11 volume has all of these files. A volume may have more than one directory 
file; the system uses these files, created by the MCR command UFD or the DCL command 
CREATE/DIRECTORY for RSX-11M-PLUS and Micro/RSX systems, to locate user files on the 
volume. 


1 User File Structure 


Data files on disk and DECtape consist of ordered sets of virtual blocks; these blocks constitute 
the virtual structure of the data files as they appear to you. Virtual blocks can be read and 
written directly by issuing READ$ and WRITE$ macro calls (see Chapter 3). The first block in 
the file is virtual block 1; subsequent virtual blocks are numbered in ascending order. 


The virtual blocks of a file are stored on the volume as logical blocks. Because virtual blocks 
and logical blocks are equal in size, and the logical block size of all volumes is 256 words, each 
virtual block is also 256 words. When access to a virtual block is requested, the virtual block 
number is mapped into a logical block number. The logical block number is then mapped to 
the physical address on the associated volume. 


5.1.2 Directory Files 


5-2 


A directory file contains directory entries. Each entry consists of a file name and its associated 
file number and file sequence number. The number of required directory files depends on the 
number of users of the volume. For single-user volumes, only an MFD is needed; for multiuser 
volumes, an MFD is required, and one User File Directory (UFD) is required for each user of 
the volume. 


The MFD contains a list of all the UFDs on the volume, and each UFD contains a list of all 
that user’s files. UFDs are identified by User Identification Codes (UICs). You can create a UFD 
by using either MCR or DCL. The following example shows how to create a UFD by using the 
MCR command UFD: 


>UFD DL1: [10,5] 


The next example shows how to create a UFD by using the DCL command CREATE 
/DIRECTORY. 


$ CREATE/DIRECTORY DU2: [LINDSEY] 


These commands are described in detail in the RSX-11M-PLUS MCR Operations Manual and 
the RSX-11M-PLUS Command Language Manual. Micro/RSX system users should refer to the 
Micro/RSX User's Guide, Volume 1. 


Figures 5-1 and 5-2 illustrate the directory structure for single-user and multiuser volumes, 
respectively. 
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5.1.3 Index File 


You create the index file for the operating system to use when you initialize a volume. During 
initialization, the information required by the system to manage the file is placed in the index 
file. The index file contains volume information and user file header blocks, which the system 
file control primitives use to manage the file. The file header blocks (see Section 5.1.4) are 
stored in the index file so that they can be located quickly. Furthermore, because a file header 
block is 256 words in length, it can be read into memory with a single access. Appendix E 
contains a detailed description of the format and content of an index file. 


Figure 5-1: Directory Structure for Single-User Volumes 
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Figure 5-2: Directory Structure for Multiuser Volumes 
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5.1.4 File Header Block 


Each file has a file header block that contains a description of the file. File header blocks are 
stored in the index file. Each file header block is 256 words long and contains the header area, 
the identification area, and the map area. Figure 5-3 illustrates the file header block and its 
contents. 


Figure 5-3: File Header Block 
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The header area identifies the block as a file header block. Each file is uniquely identified by a 
file ID consisting of two words. Files-11 ACP (F11ACP) uses the first word of the file ID (that 
is, the file number) to calculate the virtual block number of that file’s header block in the index 
file. (This calculation is done as follows: the virtual block number is the file number plus 2 
plus the number of index file bit map blocks.) F11ACP uses the second word (that is, the file 
sequence number) to verify that the header block is really the header for the desired file. 


When you request file access, both the file number and the file sequence number are specified. 
The system denies a request for access if the file sequence number does not match the 
corresponding field in the file header block that is associated with the specified file number. 


When you delete a file, its file header block space becomes available for storing a newly created 
file’s sequence number. If you attempt to access a file by file ID or by referencing an obsolete 
directory entry, this updated file sequence number ensures the rejection of the request for access. 


The identification area specifies the file’s creation name and identifies the file owner’s UIC. 
This area also specifies the creation date and time, the revision number, the date and time of 
the last revision, and the expiration date. 
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The map area provides the information needed by the system to map virtual block numbers to 
logical block numbers. 


A checksum value is computed each time the file header block is read from or written to the 
volume, thus ensuring that the file header block is transferred correctly. Appendix C contains 
a detailed description of the format and content of the file header block. 


5.2 Magnetic Tape File Processing 


5.2. 


RSX-11M-PLUS and Micro/RSX systems support the standard American National Standards 
Institute (ANSI) magnetic tape structure as described in “Magnetic Tape Labels and File Structure 
for Information Interchange,” ANSI X3.27-1978. Any of the following file/volume combinations 
can be used: 


© Single file on a single volume 

° Single file on more than one volume 

¢ Multiple files on a single volume 

° Multiple files on more than one volume 


In the preceding list, the second and fourth file and volume combinations constitute a volume 
set. 


The record format on magnetic tape differs from that on disk. When a file containing variable- 
length records or fixed-length records that cross block boundaries is copied to magnetic tape, it 
occupies more blocks on the magnetic tape than it did on the disk. This is so because magnetic 
tape record counts are larger than disk record counts, and there is unused space at the end of 
the blocks. In addition, a bit is set in the file’s File Descriptor Block (FDB) that indicates the file 
cannot cross block boundaries. 


Appendix G defines the sequence in which volume and file labels are used and the format of 
each label type. 


Note 
The ANSI file header label contains no place for the creation time or the length 
of the file. Consequently, the creation time of a file on ANSI magnetic tape is 
listed as 0. If a contiguous file is copied to ANSI magnetic tape and is then 
transferred back to disk, the resulting disk file is not marked as contiguous even 
if you use the /CO switch, because the system cannot know how much space 
to allocate for the output file when it reads from magnetic tape. 


1 Access to Magnetic Tape Volumes 


Magnetic tape is a sequential access, single-directory storage medium. Only one user can have 
access to a given volume set at a time. Only one file in a volume set can be open at a time. The 
system protects access by volume set rather than by file. On volumes produced by DIGITAL 
systems, the contents of the owner identification file determine user access rights as described 
in Appendix G. Volumes produced by non-DIGITAL systems are restricted to read-only access 
unless the access is overridden explicitly at MOUNT time. 
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5.2.2 Rewinding Volume Sets 


You can rewind a magnetic tape volume set either by using the FDOP$R macro before an 
OPEN$ or CLOSE$ macro or by using the .CTRL file control routine. Regardless of the method 
you use, FCS performs the following procedures: 


1. All mounted volumes are rewound to the beginning-of-tape (BOT). 
2. If the first volume in the set is not mounted, the device unit to be used is placed off line. 


3. If the volume is not already mounted and if the rewind was requested with an OPEN$ 
macro or by a .CTRL routine call, a request to mount the first volume appears on the 
operator’s console. 


4. If the rewind was requested with a CLOSE$ macro, no mount message is issued until the 
next volume is needed. 


5.2.3 Positioning to the Next File Position 


The standard procedure for writing a new file onto a magnetic tape is to begin writing the file 
following the end of the volume set’s last file. However, you can use the FDOP$R macro to 
indicate that the new file is to be written immediately after the labels at the end of the most 
recently closed file. 


Note 


The next file position option causes the loss of any files physically following 
this most recently closed file in the volume set. 


If, in addition to the next file position option, the rewind option also is specified, 
the file is created after the VOL1 label on the first volume of the set. All files 
previously contained in the entire volume set are lost. 


To create a file in the next file position, FA.POS must be set in FDB location F.ACTL. The 
default value for this FDB position is 0 (not FA.POS). The default indicates that the file system 
is to position itself at the logical end of the volume set to create the file. 


When you use the default, the file system makes no check for the existence of a file with the 
same name in the volume set. Therefore, a program written to use magnetic tape normally 
should specify FA.POS. 


Directory device file processors ignore the next file position option. However, programs written 
mainly for directory devices can specify the next file position option in open commands for 
output and, therefore, override a process of positioning the file system to the logical end-of-file 
normally used with ANSI magnetic tape. 
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5.2.4 Single-File Operations 


You perform single-file operations by specifying the rewind option with the FDOP$R macro 
before the open and before the close. Using this approach, you can perform operations on 
temporary tapes or work tapes (scratch tapes) as follows: 


Open the first file with the rewind option specified. 
Write the data records and close the file with rewind. 
Open the first file again for input (rewinding is optional). 
Read and process the data. 

Open the second file with rewind specified. 


Write the data records. 


N29 Pw Ne 


Close the file with rewind and perform any additional processing. 


5.2.5 Multifile Operations 


You create a multifile volume by first opening and writing and then closing a series of files 
without specifying the rewind option. You can process files sequentially on the volume by 
closing without rewind and by opening the next file without rewind. 


Opening a file for extend with the OPEN$A macro is legal only for the last file on the volume 
set. 


Perform the following tape operations to create a multifile tape volume: 
Open a file for output with the rewind option. 

Write data records and close the file. 

Open the next file without rewinding. 


Write the data records and close the file. 


a FF WON 


Repeat for as many files as desired. 


You can open files on tape in a nonsequential order, but doing so increases processing and tape- 
positioning time. Nonsequential access of files in a multifile volume set is not recommended. 


5.2.6 Using .CTRL 


You can call the .CTRL file control routine to override normal FCS defaults for magnetic tape. 
This routine might be used to perform the following tasks: 


¢ Continue processing a file on the next volume of a volume set before the end of the current 
volume is reached. 


¢ Position to the logical end-of-volume set. 
¢ Rewind a volume at other times than when opening or closing the file. 
¢ Space forward or backward any number of records. 


e Rewind a file. 
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When FCS uses the .CTRL routine to continue processing a file on the next volume, the first 
file section on the next volume is opened. File sections occur when a file is written on more 
than one volume. The portion of the file on each of these volumes constitutes a file section. 
For input files, the following .CTRL routine processing occurs: 


1. If the current volume is the last volume in the set (that is, there is no next volume), the 
end-of-file is reported to you. 


2. If another file section exists, the current volume is rewound and the next volume is mounted. 
A request to mount the next volume appears on the operator's console. 


3. The header label (HDR1) of the next file section is read and checked. 

4. If all required fields check, the operation continues. 

5. If any check fails, the operator is requested to mount the correct volume. 

For output files, the following .CTRL routine processing occurs: 

1. The current file section is closed with EOV1 and EOV2 labels and the volume is rewound. 
2. The next volume is mounted. 


3. A file with the same name and the next higher section number is opened for a write 
operation. The file set identifier is identical with the volume identifier of the first volume 
in the volume set. 


Note 
I/O buffers that are currently in memory are written on the next file section. 


When the .CTRL routine positions the tape to the logical end of the volume, the file system 
positions the tape between the two tape marks at the logical end of the last volume in the set. 


When the .CTRL routine spaces forward or backward across blocks on magnetic tape, spacing 
crosses volumes for multivolume files. 


5.2.7 Examples of Magnetic Tape Processing 


The following sections contain examples of FCS statements that process magnetic tape. Macro 
parameters not related to magnetic tape handling are omitted from these statements. 


5.2.7.1 Examples of OPENSW Macro-11 Statements to Create a New File 
All routines expect RO to contain the FDB address. For example: 
OPRWDO : 
: OPEN WITH REWIND 
FDOP$R RO,,,,,#FA.ENB!FA.RWD ;SET REWIND AND ENABLE USE 
BR OPNOUT ;OF F.ACTL 
OPNXTO: 
: OPEN FOR NEXT FILE POSITION 


FDOP$R_ RO,,,,, #FA.ENB!FA.POS ;SET POSITION TO NEXT 
BR OPNOUT ;AND ENABLE USE OF F.ACTL 
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OPROYK: 
; OPEN FILE AT END OF VOLUME KEEPING CURRENT USER 
; ACCESS CONTROL BITS 


BIC #FA.ENB,F.ACTL(RO) ;DISABLE USE OF F.ACTL 
BR OPNOUT 


OPROVO: 

; OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR 

; USER ACCESS CONTROL BITS 
FDOP$R RO,,,,,#0 ;DISABLE USE OF AND RESET 
BR OPNOUT ;F.ACTL TO ZERO 


; OPEN FILE WITH CURRENT USER ACCESS CONTROL 


OPOURO: 
BIS #FA.ENB,F .ACTL(RO) ;ENABLE USE OF F.ACTL 

OPNOUT: FDBF$R RO, ,#8192. ;OVERRIDE BLOCK SIZE FOR TAPE 
OPEN$W RO 
RETURN 


5.2.7.2 Examples of OPENSR Macro-11 Statements to Read a File 


All routines expect RO to contain the FDB address. For example: 


OPRWDI: 

; OPEN WITH REWIND 
FDOP$R RO,,,,,#FA.ENB!FA.RWD 
BR OPNIN 


OPCURI : 

; OPEN STARTING SEARCH AT CURRENT TAPE POSITION KEEPING USER 

; ACCESS CONTROL BITS 
BIC #FA.ENB,F .ACTL(RO) ;DISABLE USE OF F.ACTL 
BR OPNIN 


; OPEN USING USER ACCESS CONTROL 


OPDFLI: BIS #FA.ENB,F.ACTL(RO) ;ENABLE USE OF F.ACTL 

OPNIN: FDBF$R RO, ,#2048. ; OVERRIDE BLOCK SIZE FOR TAPE 
OPEN$R RO 
RETURN 
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5.2.7.3 Examples of CLOSES Macro-11 Statements 
All routines expect RO to contain the FDB address. For example: 
CLSCUR : 


; CLOSE LEAVING TAPE AT CURRENT POSITION AND KEEPING 
; USER ACCESS CONTROL BITS 


BIC #FA.ENB,F.ACTL(RO) ;DISABLE USE OF F.ACTL 
BR CLOSE ;DEFAULT IS LEAVING AT CURRENT 
; POSITION 


CLSRWD : 


; CLOSE REWINDING THE VOLUME 


FDOP$R RO,,,,,#FA.ENB!FA.RWD ;SET REWIND AND ENABLE USE OF 
BR CLOSE ;F.ACTL 


; CLOSE WITH USER ACCESS CONTROL BITS 


CLSDFL: BIS #FA.ENB,F.ACTL(RO) ;ENABLE USE OF F.ACTL 
CLOSE: CLOSE$ RO 
RETURN 


5.2.7.4 Combined Examples of OPENS and CLOSES Macro-11 Statements 


The following examples call routines shown in previous examples in Section 5.2.7.1. By 
combining various magnetic tape operations, you can process tape volumes in the following 
ways: 


; SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-- 


SCROUT: MOV #FDBOUT , RO ;SELECT FDB AND OPEN 


CALL OPRWDO ;OQUTPUT FILE WITH REWIND 
RETURN 

SCRIN: MOV #FDBIN,RO ;SELECT FDB AND OPEN FOR 
CALL OPRWDI ; INPUT WITH REWIND 
RETURN 

CLSCRO: MOV #FDBOUT , RO ;CLOSE SCRATCH FILE 
BR CLSVOL ;REWINDING VOLUME 


CLSCRI: MOV FDBIN,RO 
CLSVOL: CALL CLSRWD 


; MULTI-FILE VOLUME OPERATIONS 
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OPNXTI: 


; OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME 


MOV #FDBIN,RO ; SELECT FDB 
CALL OPCURI ;OPEN FILE 
RETURN 


OPENIN: 


; OPEN FILE FOR READING WHEN POSITIONED PAST IT 


MOV #FDBIN,RO ;SELECT FDB 
CALL OPRWDI 
RETURN 


; MULTI-FILE OUTPUT OPERATIONS 
OPNINT: 


; START NEW VOLUME DESTROYING ALL PAST FILES ON IT 


MOV #FDBOUT , RO ;SELECT OUTPUT FDB 
CALL OPRWDO ;OPEN WITH REWIND 
RETURN 


OPNEXT: 
; OPEN OUTPUT FILE AT NEXT FILE POSITION DESTROYING ANY FILE 
; THAT MAY BE AT OR PAST THAT POSITION 


MOV #FDBOUT , RO ;SELECT OUTPUT FDB 
CALL OPNXTO 
RETURN 


OPENDT : 
; OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET KEEPING USER 
; ACCESS CONTROL BITS 


MOV #FDBOUT , RO ;SELECT OUTPUT FDB 
CALL OPROVK 
RETURN 


OPNEOV: 
; OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND MAKE THAT THE USER 
; ACCESS CONTROL 


MOV #FDBOUT , RO ;SELECT OUTPUT FDB 
CALL OPROVO 
RETURN 


; NOT LAST FILE IN FILE SET CLOSE ROUTINE 
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CLSFLO: MOV #FDBOUT , RO ;SELECT OUTPUT FDB 


BR CLSXX 
CLSFLI: MOV #FDBIN,RO ;SELECT INPUT FDB 
CLSXX: CALL CLSCUR 
5 RETURN 


; TO APPEND TO LAST FILE 


OPEN$A #FDBOUT 
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Chapter 6 
Command Line Processing 


This chapter describes two object library routines that are available from the system object 
library, [1,1]SYSLIB.OLB. These routines may be linked with your task to provide the logical 
capabilities necessary to process terminal command line input as follows: 


Get Command Line (GCML) Accomplishes all the logical functions associated with the 
entry of command lines from a terminal, an indirect 
command file, or an online storage medium. Using GCML 
relieves you of the burden of manually coding command 
line input operations. 


Command String Interpreter (CSI) Takes command lines from the GCML command line 
input buffer and parses them into the appropriate data- 
set descriptors that FCS requires for opening files. 


The Task Builder (TKB) links these routines with your program when the task is being built. 
GCML and CSI are often used together in system or application programs as a standardized 
interface for obtaining and interpreting dynamic command line input. Figure 6-1 shows the 
flow of data during command line processing. 


Although this chapter assumes the joint use of these routines to process command line input, 
GCML and CSI may be used independently. Using one without the other, however, requires 
that you manually code the functions normally performed by the missing component. 


Invoking GCML and CSI functions requires that certain initialization be done when you write 
the source code. This initialization sets up the GCML command line input buffer, defines and 
initializes control blocks for both GCML and CSI, and establishes the necessary working storage 
and communication areas for these routines. Also, the appropriate macro calls that invoke 
GCML and CSI execution-time functions must be included in the source code at appropriate 
logical points to effect the dynamic processing of command lines. 


GCML and CSI macro calls observe the same register conventions as File Control Services 
(FCS). All registers except RO are preserved exactly as those in FCS macro calls. RO contains 
the address of the GCML control block or the CSI control block, as appropriate. 


As with all FCS macro calls, the GCML and CSI macro calls must be listed as an argument in 
a .MCALL directive (see Chapter 2) before you insert them in your program. 
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Figure 6-1: Data Flow During Command Line Processing 
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6.1 Get Command Line (GCML) Routine 


6.1. 


The Get Command Line (GCML) routine contains all the logical capabilities necessary to enter 
command lines dynamically during program execution. GCML accepts input from a terminal 
or an indirect command file that contains predefined command lines. If your program allocates 
sufficient buffer space in the file storage region (FSR) (see Chapter 2), GCML accepts commands 
that are longer than one line of terminal input. The appearance of a hyphen (-) as the last 
printing character of a command line permits the continuation of commands from one line to 
the next. 


All GCML functions require you to create and initialize a GCML control block. See 
Section 6.1.1 for a description of this macro call. The GCML run-time macro calls that 
your task may issue dynamically are described in Section 6.1.3. 


1 GCMLB§—Allocate and Initialize GCML Control Block 


This section describes the GCMLB$ macro. This macro is a necessary part of the code needed 
to dynamically obtain and execute command lines. During the assembly of your program the 
GCMLB$ macro performs the following tasks: 


e Reserves storage for and initializes a GCML control block within your program. 


e Creates and initializes an File Descriptor Block (FDB) for the indirect command file in the 
first part of the GCML control block. 


e Creates and initializes a default filename block within the GCMLE control block. 


¢ Defines the symbolic offsets for the GCML control block and initializes certain offsets to 
required values by invoking the GCMLD$ macro. These offsets are described in detail in 
Section 6.1.2. 


FCS uses the FDB to open an indirect command file. Your program may open and read a 
command file, which can use a terminal or a file-structured device such as a disk. GMCL and 
FCS initialize and maintain this FDB. 


FCS uses the default filename block for an indirect command file. If you do not specify an 
explicit filename string for an indirect command file, the values CMI for the file name and .CMD 
for the file type are assumed by default. There is no default designation for the device name. 


Format 
label: GCMLB$ maxd,prmpt,ubuf,lun,pdl,size 


Parameters 


label 
Specifies a symbol that names the GCML control block and defines its address. This label 
permits the GCML control block to be referenced directly by all the GCML run-time routines 
that require access to this structure (see Section 6.1.3). 


maxd 
Specifies a numeric value that specifies the maximum nesting depth permitted for indirect 
command files. This parameter determines the number of nested indirect command files 
that GCML can access when obtaining command line input. 
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An indirect command file, which often resides on disk, contains well-defined, nonvarying 
command sequences, which may be read directly by GCML to control such highly repetitive 
operations as TKB activities. 


If you do not specify this parameter, the default nesting level depth is 0, which effectively 
eliminates an indirect command file as a source of command line input. 


prmpt 
Specifies a 3-character American Standard Code for Information Interchange (ASCII) 
prompting sequence that you specify. The GCML routine displays this default prompt 
string at your terminal to solicit command line input. 


The ASCII prompting sequence is constructed as the following 6-byte string: 
e A carriage return ( <<CR> ) and a line feed (<LF> ) 

e The three ASCII characters that you specify 

e A right angle bracket (> ) 


The ASCII prompting sequence initializes GCML control block offset location G.DPRM (see 
Section 6.1.2). 


If you do not specify this parameter, GCML uses the right angle bracket preceded by three 
blanks as the default prompting sequence. 


ubuf 
Specifies the address of a buffer that the GCML routine uses for temporary storage of 
command line input. If you do not specify this parameter, a buffer is reserved in the GCML 
control block for command line input. The size parameter determines the length of the 
buffer. If you specify neither this parameter nor the size parameter, a 41-word buffer is 
reserved by default in the GCML control block. 


lun 
Specifies a logical unit number (LUN). The GCML routine uses the device assigned to this 
LUN as the command input device. If you do not specify this parameter, GMCL uses a 
LUN of 1 by default. 


pdl 
Specifies the address of an area reserved in your program as a push-down list. Indirect 
command file processing uses this area for working storage. Normally, you do not specify 
the pdl parameter unless you want to increase the storage for the push-down list. 


Statements logically equivalent to the following create the push-down list: 


. EVEN 
label: .BLKB G.LPDL 


The label that you supply specifies the push-down list and defines its address. G.LPDL, 
which is defined by the GCMLB$ macro, is the length (in bytes) of the push-down list. 
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The length of the push-down list is a function of the maximum number of nested indirect 
command files that may be accessed by GCML in obtaining command line input. You can 
increase the storage in the control block for the push-down list by calculating the value 
according to the following algorithm: 


1. Add 1 to the maximum nesting level depth declared with the maxd parameter described 
previously. 


2. Multiply the sum of step 1 by 16,9 to find the number of bytes that must be reserved 
for the push-down list. 


For example, if you specify 4 as the maxd parameter, you determine the length of the 
push-down list as follows: 


(4+1)*16. = 8019 bytes 


From the previous mathematical statement, note that 1619 bytes of storage are required for 
each indirect command file (4), plus another 1619 bytes as general overhead. 


size 
Specifies the size, in bytes, of the buffer reserved for command line input. The size must 
always include two extra bytes that are used internally by GCML. The default size value is 
82 (that is, 80 bytes for command line input and 2 bytes GCML overhead). 


If you want GCML to accept continuation lines, the specified value for the size parameter 
must be greater than 82. When the size is greater than 82, the bit value GE.CON is set 
in the status and mode control byte (offset G.MODE) of the GCML command block. This 
value indicates that the continuation mechanism is in effect. 


Example 


GCLBLK: GCMLB$ 4.,GCM,BUFADR,1. 
GCLBLK: GCMLB$ , ,BUFADR 
GCLBLK: GCMLB$ DEPTH,GCM,BUFADR,CMILUN, PDLIST, BUFSIZ 


Illustrates how a GCMLB$ macro call may be used in a program. 


6.1.2 GCMLD$—Define GCML Control Block Offsets and Bit Values 


The GCMLD$ macro, which the GCMLB$ macro call invokes, locally defines the GCML control 
block offsets and bit values within the current module. Table 6-1 describes these offsets and 
their bit values. 
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Table 6-1: 


Symbolic 
Offset 
Name 


G.ERR 


GCML Offsets and Bit Values 


Description 


Error return code byte 


This field initially contains 0. If any error conditions that GCML recognizes occur 
during the processing of a command line, an appropriate error code is returned to offset 
location G.ERR in the control block. Descriptions of these error bits follow: 


GE.IOR—1/O error occurred during the input of a command line. 
GE.OPR—GCML unable to open or reopen the specified command file. 
GE.BIF—Syntax error detected in the name of the indirect command file. 


GE.MDE—Attempt made to exceed the maximum permissible nesting-level depth for 
an indirect command file (see the description of the maxd parameter in Section 6.1.1). 


GE.RBG—Command line input buffer was too small for the total command. This 
condition can occur when multiple lines have been entered using the continuation 
mechanism. The input buffer contains as much of the command as possible. 


GE.EOF—End-of-file (EOF) on the top-level command file detected. 


Note 


For GE.IOR and GE.OPR, additional information concerning the 
error is available by examining the FCS error code at offset F.ERR 
from the start of the GCML block. 


The error code is set along with command file input. When the first call is issued for 
input, GCML attempts to retrieve a Monitor Console Routine (MCR) command line. 
Command level 0 is set for the first line obtained, whether it is an MCR command 
or a terminal command. If the name of an indirect command file is then entered, the 
command input level is increased to 1. Therafter, each indirect command file name 
entry increments the command input level. When the EOF is encountered on any 
given indirect command file, the command input level is decremented by 1, restoring 
the count to the previous level and reopening the associated command file. The next 
command line from that file is then read. 


If an MCR command has already been read at level 0, entering another MCR command 
when level 0 is again reached causes the error code GE.EOF to be returned to offset 
location F.ERR of the GCML control block. Hence, only one MCR command line can 
be read at level 0. If input fails at MCR level 0, then GCML continues to prompt for 
input until you press CTRL/Z to indicate terminal EOF. 


In summary, the first line of input is always read at level 0. This initial input may be an 
MCR command; if the MCR command fails or is null, the command input file (normally 
a terminal) is then opened at level 0. Multiple inputs at level 0 are permissible only in 
the latter case, that is, from the command input file. - 
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Table 6-1 (Cont.): GCML Offsets and Bit Values 


Symbolic 


Offset 
Name 


Description 


G.MODE 


G.PSDS 


Status and mode control byte 


This field is initialized at assembly time with bit definitions to specify certain default 
actions for GCML during the retrieval of a command line. 


At run time, you can reset default status and mode control bits by issuing a bit clear byte 
(BICB) instruction that takes the symbolic name of the bit to be cleared as the source 
operand. In the case of the GE.LC value (see the following text), the BICB instruction 
can override the default action. 


Descriptions of the symbolic names of the bits defined in the status and mode control 
byte follow: 


GE.IND—(Default) A command line that begins with a leading at sign (@) is an explicit 
indirect command file specification. If you reset the GE.IND bit to 0, a command line 
beginning with an at sign is returned to the calling program. 


GE.CLO— (Default) The command file currently being read is closed after each GCML$ 
macro call is issued. If you reset the GE.CLO bit to 0, GCML keeps the current command 
file open between calls for input. In this case, the file storage region (FSR) described 
in Chapter 2 must include one additional 512,9-byte buffer for command line input. 
This requirement adds to the total FSR block buffer space normally reserved for the 
maximum number of files that may be open simultaneously for record I/O processing. 


Clearing the GE.CLO bit in the status and mode control byte renders 51219 bytes of FSR 
block buffer space unavailable for other purposes because the command file remains 
open between calls for command line input. 


GE.COM—(Default) A command line that begins with a leading semicolon (;) is a 
comment. Such lines are not returned to the calling program. If you reset this bit to 0, 
a command line beginning with a leading semicolon is returned to the calling program. 


GE.CON—If the value of the size parameter of the GCMLB$ macro is greater than 82, 
the continuation mechanism is in effect by default. You must not attempt to set this bit 
in the mode byte without providing a buffer larger than 82 bytes. 


GE.LC—If this bit is set to 1 in the GCML control block at run time, lowercase 
characters in the command line are passed unaltered to your program. If this bit is 
not set, lowercase characters are changed to upppercase before being passed to your 
program. 


Prompt string descriptor 


This 2-word field is initialized at assembly time to 0 by issuing the GCMLB$ macro call 
(see Section 6.1.1). 


When you issue the GCML$ macro call to request command line input (see 
Section 6.1.3.1), the address and the length of a prompting sequence are usually 
not specified. In this case, the prompt string descriptor words in the GCML control 
block are cleared, causing GCML to type out the default prompt string contained in 
offset location G.DPRM to solicit command line input. (See the description of G.DPRM 
in the following text.) 
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Table 6-1 (Cont.): GCML Offsets and Bit Values 


Symbolic 
Offset 
Name 


G.CMLD 


G.ISIZ 


G.DPRM 


Description 


If you want to define an alternate prompt string elsewhere in the program, you may do 
so through the .ASCII directive. The address and length of this alternate prompt string 
may then be specified as the adpr and Inpr parameters in subsequent GCML$ macro 
calls. (See the description of these parameters and how they affect alternate prompt 
strings in the following text.) These parameters cause offset locations G.PSDS+2 and 
G.PSDS to be initialized with the address and the length, respectively, of the alternate 
prompt string. GCML then types out the alternate prompt string to solicit command 
line input, thereby overriding the default prompt string previously established through 
the GCMLB$ macro call. 


If you do not specify the adpr and Inpr parameters in a subsequent GCML$ macro call, 
offset location G.PSDS in the control block is reset to 0, causing GCML to revert to the 
use of the default prompt string contained in offset location G.DPRM. 


Command line descriptor 


GCML initializes this 2-word field after retrieving a command line. The address of this 
command line is returned to offset location G.-CMLD+2, and the length (in bytes) of the 
command line is returned to offset location G.CMLD. 


The contents of these word locations in the GCML control block may be passed to the 
Command String Interpreter (CSI) as the buff and len parameters in the CSI$1 macro 
call (see Section 6.2.3.1). The combination of these parameters constitutes the command 
line descriptors that enable CSI to retrieve file specifications from the GCML command 
line input buffer. 


Impure area size indicator 


This symbol is defined at assembly time, indicating the size of an impure area within 
the GCML control block to be used as working storage for pointers, flags, counters, and 
so forth, along with input from an indirect command file. In normal usage, you need 
not be concerned with this symbol. 


The space between the FDB and the default prompt string (see G-DPRM in the following 
text) is the impure area of the GCML control block. The value of the symbol S.FDB 
defines the size of the FDB. Thus, the size of the impure area is equal to G.DPRM 
minus S.FDB (G.DPRM-S.FDB). 


Default prompt string 


This 6-byte field is initialized at assembly time with the default prompt string created 
through the prmpt parameter of the GCMLB$ macro call (see Section 6.1.1). In the 
absence of the adpr and Inpr parameters in the GCML$ macro call (see Section 6.1.3.1), 
GMCL types out this default prompt string to solicit terminal input. 
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You can reference the GCML control block offsets and bit values in another module by 
establishing the appropriate symbolic definitions within that module through one of the following 


statements: 

GCMLD$ ;DEFAULT LOCAL DEFINITION 
GCMLD$ DEF$L ;LOCAL DEFINITION 

GCMLD$ DEF$G ;GLOBAL DEFINITION 


6.1.3 GCML Routine Run-Time Macros 


GCML provides the following three run-time macro calls to perform specific functions: 
GCML§ Retrieves a command line. 

RCML$__ Resets the indirect command file scan to the first (unnested) level. 

CCML$ Closes the current command file. 


These routines are described in the following sections. 


6.1.3.1 GCML$—Get Command Line Macro 


GCMLS serves as your program interface for retrieving command lines from a terminal or an 
indirect command file. You can issue this macro call at any logical point in the program to 
solicit command line input. 


Format 
GCML$ _ gclblk,adpr,Inpr 


Parameters 


gclblik 
Specifies the address of the GCML control block. This symbol must be the same as 
the symbol specified at assembly time in the label field of the GCMLB$ macro call (see 
Section 6.1.1). If you do not specify this parameter, RO is assumed to contain the address 
of the GCML control block. 


adpr 
Specifies the address of your program location containing an alternate prompt string. When 
this optional parameter and the Inpr parameter are present in the GCML$ macro call, the 
alternate prompt string appears on your terminal to solicit command line input. The normal 
default prompt string, as contained in offset location G.DPRM of the GCML control block 
(see Section 6.1.2), is thereby overridden. 


Inpr 
Specifies the length (in bytes) of the optional, alternate prompt string. If you do not specify 
this parameter, offset location G.PSDS in the GCML control block (see Section 6.1.2) is 
cleared. 
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If you specify this parameter, but do not specify the adpr parameter described previously, an 
.ERROR directive is generated during assembly that causes the error message “Prompt string 
missing” to be printed in the assembly listing. This message is a diagnostic announcement 
of an incomplete prompt string descriptor in the GCML$ macro call. If you specify this 
parameter, as well as the adpr parameter, the default prompt string is overridden. 


If you do not specify the adpr and Inpr parameters in a subsequent GCML$ macro call, offset 
location G.PSDS in the GCML control block is reset to 0. Consequently, GCML reverts to using 
the default prompt string contained in offset location G.DPRM (see Section 6.1.2). 


When you issue the GCML$ macro call, the following occurs: 


1. RO is loaded with the address of the GCML control block. If you do not specify the gclblk 
parameter, RO is assumed to contain the address of the GCML control block. If it does not 
contain that address, you must first manually initialize RO with the address of the control 
block before you issue the GCML$ macro call. 


2. The address and the length of the alternate prompt string, if specified, are stored in control 
block offset locations G.PSDS+2 and G.PSDS, respectively. These two words constitute the 
alternate prompt string descriptor. 


3. Code is generated that calls GCML to transfer a command line to the command line input 
buffer. If the last character of an input line is a hyphen (-), and if the value GE.CON 
is present in the status and mode control byte, GCML transfers commands that are longer 
than one line. The continuation lines obtained are concatenated in the input buffer with 
the continuation hyphen or hyphens removed. 


When your task first issues the GCMLS$ macro call, GCMLS$ tries to retrieve an MCR command 
line. If this attempt fails, or if the MCR command line is null, GCML uses the FDB within the 
GCML control block to open a file for command line input. If the command input device is a 
terminal, a prompt string appears on your terminal to solicit input. Any appropriate command 
input may then be entered. If the continuation mechanism is in effect, the prompt string 
reappears to solicit subsequent portions of the continued command line. 


If appropriate, you may enter an at sign (@) as the first character in the command line, followed 
by the name of an indirect command file. This file name identifies an explicit indirect command 
file from which input is to be read. GCML then opens this file and retrieves the first command 
line. On successive GCML calls, this file is read until one of the following occurs: 


e The end-of-file (EOF) is detected on the current indirect command file. In this case, the 
current indirect file is closed, the command input level count is reduced by 1, and the 
previous command file is reopened. If the command input level count is already 0 when 
EOF is detected, the error code GE.EOF is returned to offset location G.ERR of the GCML 
control block (see Section 6.1.2). 


e An indirect command file specification is encountered in a command line. In this case, the 
current indirect command file is closed (if not already closed), the new indirect command 
file is opened, and the first command line is read. 


e An RCML$ macro call is issued in the program (see Section 6.1.3.2). In this case, the current 
indirect command file is closed, and the command input count reverts to level 0; that is, 
the top-level command file is again used for input. 
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You may also enter a semicolon (;) as the first character in the command line. If GE.COM is 
set, such a line is treated as a comment and is not returned to the calling program. If GE.COM 
is clear, the line is returned to the calling program. 


Whether a command line is entered manually or retrieved from an indirect command file, the 
address and the length of the command line are returned to GCML control block offset locations 
G.CMLD+2 and G.CMLD, respectively. Together, these two words constitute the command line 
descriptors. These descriptors may be specified as the buff and len parameters in the CSI$1 
macro (see Section 6.2.3.1). 


Successful retrieval of a command line causes the Carry bit in the Processor Status Word (PSW) 
to be cleared. Any error condition that occurs during the retrieval of a command line, however, 
causes the Carry bit to be set. In addition, a negative error code is returned to offset location 
G.ERR of the GCML control block. These error codes are described in detail in Section 6.1.2. 


Examples of how you may use the GCML$ macro in a program follow. 


Examples 

GCML$ #GCLBLK 

Specifies the symbolic address of the GCML control block. 
GCML$ 


Assumes that RO contains the address of the GCML control block. The preceding examples 
both employ the default prompt string contained in offset location G.DPRM of the control block 
to solicit command line input. 


GCML$ #GCLBLK,#ADPR,#LNPR 


Specifies the address and the length of an alternate prompt string that you have defined within 
the program. GCML uses this alternate prompt string to prompt for terminal input, rather than 
using the default prompt string contained in the GCML control block. 


6.1.3.2 RCML$S—Reset Indirect Command File Scan Macro 
If you must close the current indirect command file and return to the top-level file, that is, to 
the top-level (unnested) file, you may do so by issuing the RCML$ macro. 
Format 
RCML$ | gclblk 


Parameter 


gclbik 


Specifies the address of the GCML control block. If you do not specify this parameter, RO 
is assumed to contain the address of the GCML control block. 


When you issue this macro, the current indirect command file is closed, returning control to the 
top-level (unnested) file. A subsequent GCML$ macro then retrieves the next command line 
from the 0-level command file. Note, however, that a second MCR command at level 0 cannot 
be read (see GE.EOF error code in offset location G.ERR of GCML control block, Section 6.1.2). 
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Example 
RCML$ #GCLBLK 
RCML$ RO 


Illustrates how you may use the RCML$ macro in a program. This macro call requires only the 
address of the GCML control block. 


6.1.3.3 CCML$—Close Current Command File Macro 


You may want to close the current command file between calls for input to free FSR block 
buffer space for some other use. File Control Services (FCS) normally closes the command file 
after the retrieval of a command line, provided that the GE.CLO bit in the status and mode 
control byte remains appropriately initialized (see Section 6.1.2). This bit is set to 1 at assembly 
time. If you reset this bit to 0, the current command file remains open between calls for input. 


For a program that frequently reads command files, this may be a desirable operational mode, 
because keeping the file open between calls for input reduces total file access time. However, 
should you want to close such a file to free FSR block buffer space, you may do so by issuing 
the CCML$ macro call. 


Format 
CCML$_ gclblk 


Parameter 


gclbik 
Specifies the address of the GCML control block. If you do not specify this parameter, RO 
is assumed to contain the address of the GCML control block. 


Issuing this statement closes the current command file, effectively releasing 512i bytes of FSR 
block buffer space for some other use between calls for input. If the command file is already 
closed when your task issues the CCML$ macro call, control is returned to your task. A 
subsequent GCML$ macro call then causes the command file to be reopened and the next 
command line in the file to be returned to the calling program. 


Example 
CCML$  #GCLBLK 
CCML$ RO 


Illustrates how the CCML$ macro may be used in a program. As in the RCML$ macro call 
described previously, this macro call takes a single parameter, specifically, the address of the 
GCML control block. 
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6.1.4 GCML Usage Considerations 


As noted in Section 6.1.1, the GCMLB$ macro call creates a File Descriptor Block (FDB) in the 
first part of the GCML control block. Although ordinarily you need not manipulate this FDB 
(because it is under GCML and FCS control), you can perform the following operations on this 
FDB: 


1. In an unrecoverable error situation, you can issue a CLOSE$ macro call (see Chapter 3) 
with the address of this FDB before issuing the system EXIT$ macro call. 


2. You can test the FD.TTY bit in the device characteristics byte (offset location F.RCTL) of the 
FDB to determine whether the command line just obtained was retrieved from a terminal. 


3. In the event that error code GE.IOR or GE.OPR is returned to control block offset location 
G.ERR (indicating that an I/O error has occurred during the retrieval of a command line), 
you can test offset location F.ERR of the associated FDB for a more complete error analysis. 
This FDB cell also contains an error code that may be helpful in determining the nature of 
the error condition. 


At task-build time, the Task Builder (TKB) device assignment (ASG) option should be issued 
to assign the appropriate physical device unit to the desired logical unit number (LUN). For 
example, to assign the LUN (lun parameter) in the GCMLB$ macro call (see Section 6.1.1) toa 
terminal, the following TKB option should be issued: 


ASG = TI:1 


The designation TI is a pseudo-device name that is redirected to the command input device. 
Note that the numeric value following the colon (:) must agree with the numeric value specified 
as the lun parameter in the GCMLB$ macro call. 


The ASG option is described in further detail in the RSX-11M-PLUS and Micro/RSX Task Builder 
Manual. 


As covered in the discussion on FSRSZ$ (see Chapter 2), at any given time there must be an 
FSR block buffer available for each file currently open for record 1/O operations. You must 
consider the buffer requirements of the command file when issuing the FSRSZ$ macro. (FSRSZ$ 
must be issued with a nonzero first parameter.) 


6.2 Command String Interpreter Routine 


The Command String Interpreter (CSI) routine analyzes command lines and parses them into 
their component device name, directory, and filename strings. You should be aware that CSI 
processes command lines in the following formats only: 


° dev:[g,mJoutputfilespec/switch 


More than one file specification can be specified by separating the file specifications with 
commas. 


°  dev:[g,m]outputfilespec/switch,..= dev:[g,m]inputfilespec/switch,... 
A file specification may be either of the following: 

filename.type; version 

or 


"ANSI name string"; version 
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CSI maintains a data-set descriptor within the CSI control block (see Section 6.2.1), which FCS 
may use when opening files. The run-time routines that analyze and parse command lines for 
your calling program are described in Section 6.2.3. 


Using CSI requires that the CSI control block offsets and bit values be defined and that a 
control block be allocated within the program. The macro described in the following section 
accomplishes these requisite actions. 


6.2.1 CSI$S—Define CSI Control Block Offsets and Bit Values Macro 


Following is the only initialization coding required for CSI at assembly time: 


CSI$ ;DEFINES CSI CONTROL BLOCK OFFSETS 
;AND BIT VALUES LOCALLY 
. EVEN ;WORD ALIGNS CSI CONTROL BLOCK 


CSIBLK: .BLKB C.SIZE ;NAMES CSI CONTROL BLOCK AND 
: ;ALLOCATES REQUIRED STORAGE 


The CSI$ macro does not generate any executable code. The CSI control block resulting from 
the .BLKB directive allows communication between CSI and the calling program. The symbol 
C.SIZE specifies the length of the control block. C.SIZE is defined during the expansion of the 
CSI$ macro. Expanding this macro also causes a local definition of the symbolic offsets and bit 
values within the CSI control block. 


You can cause the control block offsets to be defined globally within the current module. This 
is done by specifying DEF$G as an argument in the CSIS$ initialization macro call, as follows: 


CSI$ DEF$G 


6.2.2 CSI$S Macro Control Block Offset and Bit Value Definitions 


The CSI$ macro locally defines the symbolic offsets and bit values shown in Table 6-2 within 
the CSI control block. 


Table 6-2: CSI$ Offsets and Bit Values 


Symbolic 
Offset 
Name Description 


C.TYPR Command string request type 


This byte field indicates which type of file specification is being requested. Depending 
on whether an input or output file specification is being requested (see the io parameter 
in the CSI$2 macro call described in Section 6.2.3.2), the corresponding bit in this byte 
is set. The bit definitions for this byte are as follows: 


CS.INP—Indicates that an input file specification is being requested. 
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Table 6-2 (Cont.): CSI$ Offsets and Bit Values 


Symbolic 
Offset 
Name 


C.STAT 


C.CMLD 


Description 
CS.OUT—Indicates that an output file specification is being requested. 
Command string request status 


This byte field reflects the status of the current command line request. The bits in this 
field are initialized according to the following bit definitions: 


CS.EQU—Indicates that an equal sign (=) has been detected in the current command 
line, signifying that the command line contains both output and input file specifications. 
Once CS.EQU is set, CSI1 and CSI2 processing preserves the value of CS.EQU. 


CS.NMF—Indicates that the current file specification contains a filename string. 
Accordingly, control block offset locations C.FILD+2 and C.FILD (see the entry for 
C.FILD) are initialized with the address and the length (in bytes), respectively, of the 
command line segment that contains the filename string. If no filename string is present, 
this bit is not set, and the filename string descriptors in the control block are cleared. 


CS.DIF—Indicates that the current file specification contains a directory string. Thus, 
control block offset locations C.DIRD+2 and C.DIRD (see the description following for 
C.DIRD) are initialized with the address and the length (in bytes), respectively, of 
the command line segment that contains the directory string. If no directory string is 
present, this bit is not set. In this case, any residual nonzero values in the directory 
string descriptor cells that pertain to a previous command string request of similar type 
are used by default (see the description of C.TYPR). Thus, FCS uses the last directory 
string encountered in a file specification. 


CS.DVF—Indicates that the current file specification contains a device name string. 
Similarly, control block offset locations C.DEVD+2 and C.DEVD (see the description of 
C.DEVD) are initialized with the address and the length (in bytes), respectively, of the 
device name string. If no device name string is present, this bit is not set. Like CS.DIF 
(see the previous description of CS.DIF), any residual nonzero values in the device name 
descriptor cells that pertain to a previous command string request of similar type are 
used by default. Thus, the last device name string encountered in a file specification is 
used. 


CS.WLD—Indicates that the current file specification contains an asterisk (*), which 
signals the presence of a wildcard specification. 


CS.MOR— Indicates that the current file specification is terminated by a comma (,), 
which indicates that more file specifications are to follow. If this bit is not set, it signifies 
that the end of the input or output file specification has been reached. 


Command line descriptor 


This 2-word field is initialized with the length (in bytes) and the address, respectively, 
of the compressed command line. In other words, the values returned to these cells are 
the CSI output after it scans a file specification and removes all nonsignificant characters 
from the string (that is, nulls, unquoted blanks and tabs, and RUBOUTSs). 
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Table 6-2 (Cont.): CSI$ Offsets and Bit Values 


Symbolic 
Offset 
Name 


C.DSDS 


C.DEVD 


C.DIRD 


C.FILD 


Description 


CSI uses the values contained in these cells as the descriptors of the compressed 
command line to be parsed (see CSI$2 macro call in Section 6.2.3.2). 


Data-set descriptor pointer 


This pointer defines the address of the 6-word data-set descriptor in the CSI control 
block. This structure is functionally identical to the manually created data-set descriptor 
detailed in Chapter 2. 


You can use this symbol to initialize offset location F.DSPT in the FDB associated with 
the file to be processed. Thus, FCS is able to retrieve the American Standard Code for 
Information Interchange (ASCII) information from this structure that it needs to open 
files. 


Assembly-time initialization of F.DSPT in the associated FDB may be accomplished as 
follows: 


FDOP$A 1,CSIBLK+C.DSDS 


In this example, CSIBLK is the address of the CSI control block and C.DSDS represents 
the beginning address of the descriptor strings in the CSI control block (see the following 
entries for offset names) identifying the requisite ASCII file name information. 


Run-time initialization of F.DSPT in the associated FDB may also be accomplished by 
using the dspt parameter of the FDOP$R macro call (see Chapter 2) or the generalized 
OPEN$x macro call (see Chapter 3). 


Device name string descriptor 


This 2-word field contains the address (C.DEVD+2) and the length in bytes (C.DEVD) 
of the most recent device name string (of those with the same request type) encountered 
in a file specification. Note that the colon that follows the device name is not included 
in the device name string. 


Directory string descriptor 


This 2-word field contains the address (C.DIRD+2) and the length in bytes (C.DIRD) of 
the most recent directory string (of those with the same request type) encountered in a 
file specification. Note that the brackets are included as part of the directory string 


Filename String Descriptor 


This 2-word field contains the address (C.FILD+2) and the length in bytes (C.FILD) of 
the filename string in the current file specification. 


If an error condition is detected by the command syntax analyzer during the syntactical 
analysis of a command line (see Section 6.2.3.1), a segment descriptor is returned to 
this field, defining the address and the length of the command line segment in error. 
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Table 6-2 (Cont.): CSI$ Offsets and Bit Values 


Symbolic 


Offset 
Name 


Description 


a Se Se 


C.SWAD 


C.MKWI1 


C.MKW2 


C.SIZE 


C.EXPS 


Current switch table address 


This word location contains the address of the switch descriptor table specified in the 
current CSI$2 macro call (see Section 6.2.3.2). 


CSI mask word 1 


This word indicates the particular switches present in the current file specification after 
each invocation of the CSI$2 macro call. The switch mask for each of the defined 
switches encountered in a file specification between delimiting commas is inserted into 
this location by a logical OR operation. This word is reset with each call to CSI$2 


The mask for a switch is specified in the CSI$SW macro call (see Section 6.2.4.1). 
When a switch is encountered in a file specification for which a defined mask exists, 
the corresponding bits in C.MKW1 are set. By testing C.MKW1, you can determine the 
particular combination of defined switches present in the current file specification. 


CSI mask word 2 
This word provides you with an indication of switch polarity. 


When a switch is present in a file specification and you do not negate that switch, 
the defined mask for that switch is inserted into C.MKW2 by a logical OR operation 
in the same manner as described previously for C_-MKW1. Conversely, when a switch 
is present in a file specifier and you do negate that switch, the corresponding bits in 
C.MKW2 are cleared. Thus, you can check the polarity of each switch that C MKW1 
indicates is present by examining the corresponding bits in C.:MKW2. This word is reset 
with each call to CSI$2 


Control block size indicator 


This symbol, which is defined during the expansion of the CSI$ macro, represents the 
size in bytes of the CSI control block. 


User task expansion buffer size 


This symbol is the constant for your task’s expansion buffer size (for logical name 
expansion). It is currently set to 48,). See the description of the CSI$4 routine in 
Section 6.2.3.3 for more information. 


SS a i 
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6.2.3 CSI Run-Time Macros 


Three run-time macro calls in CSI invoke routines that perform the following functions: 


CSI$1 Initializes the CSI control block, analyzes the command line (normally contained in 
the GCML command line input buffer), removes nonsignificant characters from the 
line, and checks the line for syntactic validity. This macro also initializes certain 
cells in the CSI control block with the address and the length, respectively, of the 
validated and compressed command line. 


CSI$2 Parses a file specification in the validated and compressed command line into 
its component device name, directory, and filename strings, and processes any 
associated switches and accompanying switch values. In addition, certain cells 
in the CSI control block are initialized with the appropriate string descriptors for 
subsequent use by FCS in opening the specified file. 


CSI$4 Expands a file specification and returns a data-set descriptor and flag word that refer 
to this expanded file specification. The file specification string is not expanded into 
the original buffer but into a separate buffer in the file storage region (FSR). The 
use of CSI$4 is recommended when parsing logical file specification strings. 


6.2.3.1 CSI$1—Command Syntax Analyzer 


The CSI$1 macro invokes a routine called the command syntax analyzer. This routine analyzes 
a command line, which is normally read into the GCML command line input buffer, and checks 
it for correct syntax. In addition, it compresses the file specifications in the command line by 
removing all nonsignificant characters (that is, null, RUBOUT, and unquoted tabs and blanks). 
Finally, the command syntax analyzer initializes offset locations C.CMLD+2 and C.CMLD in the 
CSI control block (see Section 6.2.2) with the address and the length (in bytes), respectively, of 
the validated and compressed command line. Each file specification in the command line is then 
parsed into its component device name, directory, and filename strings during each successive 
time the CSI$2 macro call is issued (see Section 6.2.3.2). 


Format 
CSI csiblk,buff,len 


Parameters 


csiblk 
Specifies the address of the CSI control block. If you do not specify this parameter, RO is 
assumed to contain the address of the CSI control block. 


buff 
Specifies the address of a command line input buffer. This parameter initializes CSI control 
block offset location C.CMLD+2, enabling CSI to retrieve the current command line from a 
command line input buffer. 


If you do not specify this parameter, you must manually initialize CSI control block offset 
location C.CMLD+2 with the address of a command line input buffer before issuing the 
CSI$1 macro call. The following statement shows one way to manually initialize this 
location: 


MOV GCLBLK+G.CMLD+2,CSIBLK+C .CMLD+2 
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len 
Specifies the length of the command line input buffer. Similarly, this parameter initializes 
CSI control block offset location C.CMLD, thus completing the 2-word descriptor that 
enables CSI to retrieve the current command line from the input buffer. 


As with the buff parameter described previously, if you do not specify this parameter, you 
must manually initialize CSI control block offset location C.CMLD with the length of the 
command line input buffer before issuing the CSI$1 macro call. The following statement 
shows one way to manually initialize this location: 


MOV GCLBLK+G.CMLD,CSIBLK+C.CMLD 


The combination of the buff and len parameters described previously enables CSI to analyze 
the current command line. Following the analysis of the command line, CSI updates offset 
location C.CMLD with the length of the validated and compressed command line. 


If a syntactical error is detected during the validation of the command line, the Carry bit in the 
Processor Status Word (PSW) is set, and offset locations C.FILD+2 and C.FILD in the CSI control 
block (see Section 6.2.2) are set to values that define the address and the length, respectively, 
of the command line segment in error. 


Examples of how the CSI$1 macro call may be used in a program follow. 


Examples 
CSI$1 #CSIBLK , #BUFF , #LEN 


Shows symbols that represent the address and the length of a command line to be analyzed 
(not necessarily the line contained in the GCML command line input buffer). 


CSI$1 RO, GCLBLK+G .CMLD+2 , GCLBLK+G . CMLD 


Assumes that RO has been preset with the address of the CSI control block; the next two 
parameters are direct references to the command line descriptor words in the GCML control 
block. 


CSI$1 #CSIBLK 


Assumes that the required descriptor values are already present in offset locations C.CMLD+2 
and C.CMLD of the control block (CSIBLK) as the result of prior action. 


6.2.3.2 CSIS2—Command Semantic Parser Macro 


The CSI$2 macro invokes the command semantic parser. This routine uses the values in 
CSI control block offset locations C.CMLD+2 and C.CMLD as the address and the length, 
respectively, of the command line to be parsed. The routine then parses the referenced line into 
its component device name, directory, and filename strings. The equal sign in the command 
line indicates that the string that follows is an input file specification. In addition, 2-word 
descriptors for these strings are stored in a 6-word data-set descriptor in the CSI control block, 
beginning at offset location C.DSDS (see Section 6.2.2). This field is functionally equivalent to 
the data-set descriptor created manually in your program (see Chapter 2). 


The parser also decodes any switches and associated switch values present in a file specification, 
provided that the address of the appropriate switch descriptor table has been specified in the 
CSI$2 macro call (see the following text). The CSI switch definition macro calls are described 
in detail in Section 6.2.4. 
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Format 
CSI csiblk,io,swtab 


Parameters 


csibik 
Specifies the address of the CSI control block. If you do not specify this parameter, RO is 
assumed to contain the address of the CSI control block. 


Specifies a symbol that identifies the type of file specification to be parsed. You may specify 
either of the following two symbolic arguments in this parameter field: 


INPUT The next input file specification in the command line is to be parsed. 
OUTPUT _ The next output file specification in the command line is to be parsed. 


You must initialize offset location C.TYPR in the CSI control block (see Section 6.2.2), 
either manually or through the CSI$2 macro call, with the type of file specification being 
requested. If arguments other than the symbolic arguments defined previously are specified 
in the CSI$2 macro call, an .ERROR directive is generated during assembly that causes 
the error message “Incorrect request to .CSI2” to be printed in the assembly listing. This 
diagnostic message alerts you to the presence of an invalid io parameter in the CSI$2 macro 
call. 


swtab 

Specifies the address of the associated switch descriptor table. You specify this optional 
parameter only if you suspect that the file specification contains a switch to be decoded. 
For you to specify this parameter, the program must already contain a switch descriptor 
table, which you created with the CSI$SW macro (see Section 6.2.4.1). In addition, if the 
switch to be decoded has any associated switch values, the program must already contain 
an associated switch value descriptor table, which you create with the CSI$SV macro call 
(see Section 6.2.4.2). 


This parameter initializes offset location C.SSWAD in the CSI control block (see 
Section 6.2.2). If you do not specify this parameter, FCS uses any residual nonzero 
value in this cell by default as the switch descriptor table address. 


You can also initialize offset location C'SWAD manually prior to issuing the CSI$2 macro 
call, as shown in the following statement: 


MOV #SWTAB,CSIBLK+C.SWAD 


SWTAB is the symbolic address of the associated switch descriptor table. (The switch table 
must be aligned on an even address.) 


If an error condition occurs during the parsing of the file specification, the Carry bit in the PSW 
is set, and control is returned to the calling program. The possible error conditions that may 
occur during command line parsing include the following: 


e The request type is invalid; that is, offset location C.TYPR in the CSI control block (see 
Section 6.2.2) is incorrectly initialized. 
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¢ The file specification contains a switch, but the address of the switch descriptor table is 
not specified in the CSI$2 macro call, or the switch descriptor table does not contain a 
corresponding entry for the switch. 


e The file specification contains an invalid switch value. 


¢ The number of values accompanying a given switch in the file specification is greater than 
the number of corresponding entries in the switch value descriptor table for decoding those 
values. 


* The file specification contains a negative switch, but the corresponding entry in the switch 
descriptor table prevents you from negating the switch (see the nflag parameter of the 
CSI$SW macro call in Section 6.2.4.1). 


Examples of how the CSI$2 macro may be used in a program follow. 


Examples 

CSI¢2 #CSIBLK, INPUT, #SWIBL 

Shows a request to parse an input file specification, which may include an associated switch. 
CSI$2 RO, OUTPUT, #SWTBL 


Assumes that RO presently contains the address of the CSI control block and parses an output 
file specification, which also may include a switch. 


CSI$2.  #CSIBLK, INPUT 


Requests to parse an input file specification and to disallow any accompanying switches. 


6.2.3.3 CSIS4—Command Semantic Parser Macro 


Use CSI$4 in the same way that you use CSI$2. However, CSI$4 is the preferred method of 
parsing logical names. Using CSI$4 causes the same function as CSI$2 except that CSI$4 allows 
all tasks to use logical names correctly, except under the following two conditions: 


1. The task saves the data-set descriptor for one call to CSI$2 and then calls CSI$2 again, 
expecting to be able to use the first data-set descriptor at a later time. 


2. The task assumes that the data-set descriptor points into the original string. 


CSI$4 cannot be called repeatedly using the previous data-set descriptor. The reason is that 
whenever a parse is done, whether by the .PARSE routine (see Chapter 4), or the CSI$4 macro, 
or the .EXPLG routine, the expanded string is always put into the FSR area of the task. If your 
task repeatedly calls CSI$4, each call overwrites the previous call. CSI$4 uses this common 
buffer for input file specifications, but CSI$4 uses a separate expansion buffer for output file 
specifications. This permits CSI$4 to process input and output file specifications simultaneously. 


To allow multiple calls to CSI$4, another parameter is added to the following CSI macro: 
CSI$2  #CSIBLK, INPUT, #CSISWT 
The resulting CSI macro is as follows: 


CSI$4 #CSIBLK, INPUT, #CSISWT, #DSCBLK 
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The DSCBLK parameter is a pointer to a 2-word descriptor block that specifies the expanded 
command line buffer. The descriptor block contains the following two words: 


Word 0 Contains the size of the expanded command line buffer. 
Word 1 Contains the address of the expanded command line buffer. 


The descriptor block and the command line expansion buffer are allocated in your task’s address 
space. The size of the expansion buffer should be as large as any possible single file specification. 
Therefore, C.EXPS, currently set to 4819, should be used. If the buffer is too small, an error is 
returned. If either value in the descriptor block is 0, the expansion area in the FSR is used. 


Logical name expansion requires a relatively large amount of system overhead. The following 
steps should be followed to reduce the overhead demand: 


1. Do not change CSI$2 macros to CSI$4 macros when you want your task to only scan the 
line for switches or files without opening any files found. In this case, changing CSI$2 to 
CSI$4 only adds to the extra translation required. 


2. Include the following line before any call to .PARSE: 
BISB #FL.AEX,F.FLG(RO) ;RO is the FDB address 
This code line informs .PARSE that the string has already been expanded and .PARSE need 


not repeat the expansion. 


6.2.4 CSI Switch Definition Macros 


The following macro calls create the requisite switch descriptor tables in your program for 
processing switches that appear in a file specification: 


CSI$SW Creates an entry in the switch descriptor table for a particular switch that you 
expect to encounter in a file specification. 


CSI$SV Creates a matching entry in the switch value descriptor table for the switch defined 
through the CSI$SW macro. 


CSI$ND Terminates a switch descriptor table or a switch value descriptor table created 
through the CSI$SW or the CSI$SV macro call, respectively. 


These macro calls are described in the following sections. 


6.2.4.1 CSISSW—Create Switch Descriptor Table Entry Macro 


You must define a matching entry in the switch descriptor table for each switch that you expect 
your task to encounter in a file specification. If no switch descriptor table is specified or no 
corresponding entry exists, the presence of a switch in the command line causes an error. When 
your task issues a CSI$2 macro (see Section 6.2.3.2) and the address of a switch descriptor table 
is specified, the following processing occurs: 


1. For each switch encountered in a file specification, CSI searches the switch descriptor table 
for a matching entry. If either the switch descriptor table address is not specified, or a 
matching switch entry is not found in the table, that switch is considered invalid. As a 
result, the Carry bit in the PSW is set, any remaining switches in the file specification are 
bypassed, and control is returned to the calling program. 
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2. If a matching entry is found in the switch descriptor table, mask word 1 in the CSI control 
block is set according to the defined mask for that switch (see C.MKW1, Section 6.2.2). 


3. The negation status of the switch is determined. If you do not negate the switch, the 
corresponding bits in mask word 2 (C.MKW2) in the CSI control block are set according 
to the defined mask for that switch. If you negate the switch but negation is not allowed, 
the switch is considered invalid. In this case, the error sequence described in step 1 would 
occur. However, if you negate the switch, and negation is allowed, the corresponding bits 
in C.MKW2 are cleared. 


The negation flag for a switch is established through the nflag parameter of the CSI$SW 
macro (described in the following text). 


4. If the optional mask word address is not present in the corresponding switch descriptor 
table entry, that is, if you did not specify the mkw parameter in the associated CSI$SW 
macro, switch processing continues with step 7. If, however, you did specify the optional 
mask word address, switch processing continues with step 5. 


5. If SET has been specified as the clear/set flag in the corresponding switch descriptor table 
entry, and the switch is not negated, then the corresponding bits in the optional mask word 
are set according to the defined mask for that switch. If, however, you negate the switch, 
the corresponding bits in the optional mask word are cleared. 


You specify the clear/set flag as the csflg parameter in the CSI$SW macro. 


6. If CLEAR has been specified as the clear/set flag in the corresponding switch descriptor 
table entry, and the switch is not negated, the corresponding bits in the optional mask word 
are cleared. Conversely, if you negate the switch, the corresponding bits in the optional 
mask word are set. 


7. If a switch value accompanies a switch in a file specification, File Control Services (FCS) 
uses the associated switch value descriptor table created through the CSI$SV macro call 
(see Section 6.2.4.2) to decode the value. There must be at least as many entries in the 
switch value descriptor table as there are such values accompanying the switch in the file 
specification. If the switch value descriptor table is incomplete, or an invalid switch value 
is encountered, or the address of the switch value descriptor table is not present in the 
associated switch descriptor table, the switch is invalid, and the error sequence described in 
step 1 would occur. 


You specify the address of the switch value descriptor table as the vtab parameter in the 
CSI$SW macro call. 

Format 
label: CSISSW sw,mk,mkw,csflg,nflg,vtab,compflg 


Parameters 


label 
Specifies an optional symbol that names the resulting switch descriptor table entry and 
defines its address. To establish the address of a switch descriptor table, the first CSI$SW 
macro call issued in the program must include a label. This label allows the table to be 
referenced by other instructions in the program. 
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sw 
Specifies the switch name to be stored as an entry in the switch descriptor table. This name 
may comprise any number of alphabetic characters. CSI compares the name entered on 
the command line with this switch name as entered in the switch descriptor table. This is 
a required parameter; if you omit it, the assembler generates an .ERROR directive during 
assembly that causes the error message “Missing switch name” to be printed in the assembly 
listing. 


mk 
Specifies a mask that you define for the switch specified through the sw parameter. To 
enable CSI to indicate the presence of a given switch in a file specification, you must define 
a mask value for the switch, as follows: 


ASMSK 
NUMSK 


wou 
_ 


VWMSK = 40000 
XYMSK = 100000 


The octal value that you assign to each symbol defines a unique bit configuration. This 
configuration is to be set in CSI mask word 1 (C.MKW1) of the control block when a defined 
switch is encountered in a file specification. 


When you specify the appropriate symbol as the mk parameter in the CSI$SW macro call, 
the corresponding mask value is stored in the resulting switch descriptor table entry. Thus, 
a mechanism is established through which you can determine the particular combination 
of switches present in a file specification. For every matching entry found in the switch 
descriptor table, the corresponding bits are set in C.MKW1. 


mkw 
Specifies the address in your program storage of a mask word that CSI changes each time 
it changes C.MKW1. CSI stores the same value into this mask word that it stores into 
C.MKW1. This mask word can be manipulated, that is, changed or tested by the SET and 
CLEAR functions or by instructions in your program. You set the SET and CLEAR functions 
by using the csflg parameter. 


Such an optional word may be reserved through a statement logically equivalent to the 
following: 


MASKX: .WORD 0 
csfig 
Specifies a symbolic argument that specifies the clear/set flag for a given switch. This 


parameter is optional; if you do not specify it, SET is assumed. You may specify either one 
of two symbolic arguments for this parameter, as follows: 
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CLEAR Indicates that the bits in the optional mask word corresponding to the switch mask 
are to be cleared, provided that you did not negate the switch. (If you negate the 
switch, the bits are set.) 


SET Indicates, conversely, that the bits in the optional mask word in your task 
corresponding to the switch mask are to be set, provided that you did not negate 
the switch. (If you negate the switch, the bits are cleared.) 


If you specify other than SET or CLEAR, the assembler generates a .ERROR directive that 
causes the error message “Invalid set/clear spec” to be printed in the assembly listing. 


nfig 
Specifies an optional negation flag for the switch. If you specify this parameter, it indicates 
that the switch can be negated, for example, /-LI or /NOLI. 


If you specify this parameter as other than NEG, the assembler generates an .ERROR 
directive that causes the error message “Invalid negate spec” to be printed in the assembly 
listing. If you do not specify this parameter, the assumption is that switch negation is not 
allowed. 


vtab 
Specifies the address of the switch value descriptor table associated with this switch. If you 
specify this optional parameter, it allows CSI to decode any switch values accompanying 
the switch, provided that you have defined an associated switch value descriptor table entry 
for that switch. The CSI$SV macro defines the switch value descriptor table. (If you specify 
the vtab parameter in the CSI$SV macro, you need not specify it in the CSI$SW macro 
call.) 


compfig 
Defines the method CSI uses to compare the switch name entered on the command line 
with the value entered in the switch descriptor table by the sw parameter. Either LONG or 
EXACT may be specified. The default value is entered if you do not specify a value. 


Following is a description of each value: 


Default If you do not code the parameter, only the first two characters of the switch name 
(specified by sw) are entered into the switch descriptor table and only these two 
characters are compared when the command line is parsed. Additional characters 
in the command line switch name are ignored. 


LONG _ All characters specified by the sw parameter are entered in the switch descriptor 
table. During compare processing, the first characters of the switch name on 
the command line must exactly match the value for the switch in the switch 
descriptor table. Additional characters in the command line switch name are 
ignored. 


EXACT All characters specified by the sw parameter are entered in the switch descriptor 
table. During compare processing, all the characters of the switch name on the 
command line must exactly match the value in the switch descriptor table. Extra 
characters in either the command line or the table are treated as an error. 
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The switch table must be aligned on an even address. The format of the switch descriptor table 
entry created by the CSI$SW macro is shown in Figure 6-2. 


The switch name characters precede the control information in the table. The sign bit of each 
word indicates whether the following word contains more switch name characters. A sign bit 
set to 1 indicates that the next word contains more switch name characters; whereas, a sign bit 
set to 0 indicates that this is the last word containing switch name characters. 


If the number of characters in the switch name is odd, the high-order byte of the last word 
contains zeros, and CSI ignores it. 


The sign bit of the first byte of the last word of the switch name is the EXACT match bit. If 
this bit is set to 1, additional characters in the switch name on the command line are treated as 
an error by CSI; if this bit is set to 0, additional characters are ignored. 


The switch name characters are followed by entry control information consisting of the CSI 
mask word, the address of the area task of a mask word corresponding to the CSI mask word, 
and the address of the switch value table. 


A bit setting of 1 in the low-order bit of the address of your mask word indicates the CLEAR 
function; a bit setting of 0 indicates the SET function. 


The last word of the switch descriptor table entry contains the address of the switch value table. 
A bit setting of 1 in the low-order bit of this word indicates that the switch may be negated. 


Figure 6-2: Format of Switch Descriptor Table Entry 


15 0 
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Example 
ASSWT: CSI$SW AS,ASMSK,MASKX,SET, , ASVTBL 
CSI$SW NU,NUMSK,MASKX, CLEAR , NEG, NUVIBL 
CSI$ND ;END OF SWITCH DESCRIPTOR TABLE. 


Shows a 2-word entry switch descriptor table created through successive CSI$SW macro calls. 
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The first parameter in the first statement creates an entry in the switch descriptor table for the 
/AS switch. The second parameter is an equated symbol that defines the switch mask, and 
the third parameter (MASKX) is the address of an optional mask word in your task (see the 
description of the mkw parameter). The fourth parameter indicates that the bits in MASKX that 
correspond to the switch mask are to be set. The fifth parameter (the negation flag) is null. The 
last parameter is the address of the associated switch value descriptor table. 


The second statement creates a switch descriptor table entry for the /NU switch. In contrast to 
the first statement, the fourth parameter (CLEAR) indicates that the bits in the optional mask 
word (MASKX) in your task that correspond to the switch mask are to be cleared. The fifth 
parameter (NEG) allows the switch to be negated, and the last parameter is the address of the 
switch value descriptor table associated with this switch. 


Note that the switch descriptor table entry macros are terminated with the CSI$ND macro (see 
Section 6.2.4.3). 


6.2.4.2 CSI$SSV—Create Switch Value Descriptor Table Entry Macro 


CSI$SV defines a switch value descriptor table entry. For every switch value that you expect 
your task to find with a given switch in a file specification, a corresponding switch value 
descriptor table entry must be defined in your program so that the switch value can be decoded. 
This macro creates a 2-word entry in the switch value descriptor table. The format of this table 
is shown in Figure 6-3. 


Format 
CSI$SV_type,adr,len 


Parameters 


type 
Specifies the conversion type for the switch value. Any one of four symbolic values may 
be specified. The possible conversion types include the following: 


ASCII Indicates that the switch value is to be treated as an ASCII string. If you 
quote the string, the quotes are returned in the buffer as part of the string. 
If a quote appears anywhere in the switch value, all characters following it, 
up to the end of the line or another quote, are included in the string. 


NUMERIC Indicates a numeric switch value is to be converted to binary, using octal as 
a default conversion radix. 


OCTAL Indicates a numeric switch value is to be converted to binary, using octal as 
a default conversion radix. 


DECIMAL Indicates a numeric switch value is to be converted to binary, using decimal 
as a default conversion radix. 


If any parameter is specified other than these, a .ERROR directive is generated during 
assembly that causes the error message “Invalid conversion type” to be printed in the 
assembly listing. If you do not specify any of the previously described parameters, ASCII 
is assumed by default. 
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adr 
Specifies the address of your program location that is to receive the resultant switch value at 
the conclusion of switch processing. This parameter is required; if not specified, a ERROR 
directive is generated during assembly that causes the error message “Value address missing” 
to be printed in the assembly listing. 


len 
Specifies a numeric value that defines the length (in bytes) of the area that is to receive 
the switch value that results from switch processing. This parameter is also required; if not 
specified, a .ERROR directive is generated during assembly that causes the error message 
“Length Missing” to be printed in the assembly listing. 


The format of a switch value descriptor table entry created by a CSI$SV macro is shown in 
Figure 6-3. 


The low-order byte of the first word in the switch value descriptor table indicates whether the 
conversion type is ASCII or numeric. The low-order byte of this word is set to 1 if ASCII is 
specified; it is set to 2 if NUMERIC or OCTAL is specified; and it is set to 3 if DECIMAL is 
specified. The high-order byte of this word indicates the maximum allowable length (in bytes) 
of the switch value. 


If the conversion type is ASCII, the len parameter reflects the maximum number of ASCII 
characters that can be deposited in the area defined through the adr parameter. The high-order 
byte of the first word in the switch value table then reflects the maximum length of the ASCII 
string. If the number of characters in the switch value exceeds the specified length, the extra 
characters are ignored. If, however, the actual number of ASCII characters present in the switch 
value falls short of the specified length, the remaining portion of the area receiving the resultant 
value is padded with nulls. 


If the conversion type is numeric, the length of the resulting binary value is either 2 bytes or 
4 bytes. If the size field is less than 4 bytes, 2 bytes are stored. If the size field is greater than 
4 bytes, 4 bytes are stored. You must align the buffer on a word boundary. 


If you specify the default conversion type for a switch value on numeric conversions, you 
can override it with a number sign (#) or a period (.). Preceding a numeric value with a 
number sign (for example, #10) forces the conversion type to octal; a numeric value followed 
by a period (for example, 10.) forces the conversion type to decimal. Note also that you may 
precede a numeric switch value with a plus sign (+) or a minus sign (—). The plus sign is the 
default assumption. If you specify an explicit octal switch value by using the number sign (#), 
the arithmetic sign indicator (+ or -), if included, must precede the number sign (for example, 
-#10). 


If the conversion type is decimal, the switch value is evaluated as a single number; an overflow 
into the high-order bit (bit 15) causes an error condition. However, if the conversion type is 
octal, a full 16-bit value may be specified. 
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Figure 46-3: Format of Switch Value Descriptor Table Entry 


16 0 


Switch Value Length Conversion Type 


Address of Location Receiving Switch Result 
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Examples of how the CSI$SV macro call may appear in a program follow. 


Examples 
ASVIBL: CSI$SV ASCII, ASVAL,3 

CSI$SV ASCII, ASVAL+4,3 

CSI$ND ;END OF SWITCH VALUE TABLE 
NUVTBL: CSI$SV OCTAL,NUVAL,2 


CSI$SV DECIMAL,NUVAL+2,2 
CSI$ND ;END OF SWITCH VALUE TABLE 


In these examples, the first parameter in the CSI$SV macro defines the conversion type. The 
next two parameters, in all cases, define the address and the length of the program location 
that is to receive the resultant switch value. 


You may reserve the required storage for the first switch value table ASVTBL: as follows: 
ASVAL: .BLKW 4 ;ASCII VALUE STORAGE 


You can similarly reserve the required storage for the second switch value table NUVAL: through 
the following statement: 


NUVAL: .BLKW 2 ;NUMERIC VALUE STORAGE 


Note again that switch value tables are terminated with the CSI$ND macro call. 


6.2.4.3 CSISND—Define End of Descriptor Table 


CSI$ND terminates descriptor tables with a 1-word entry. Switch descriptor tables and switch 
value descriptor tables must be terminated with a 1-word end-of-table entry. You can create 
this word, which contains 0, with the CSI$ND macro call. 


This macro call takes no arguments. The examples in Sections 6.2.4.1 and 6.2.4.2 illustrate the 
use of this macro call. 
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Chapter 7 
The Table-Driven Parser (TPARS) 


This chapter describes the table-driven parser (TPARS), which parses command lines. TPARS 
permits you to define and parse command lines in a unique syntax by using TPARS-supplied 
macros, built-in variables, and your own code. 


TPARS parses command lines according to syntax and semantics or meaning. The command 
line is made up of syntax elements. TPARS evaluates each syntax element of the command 
line based on a predefined arrangement of those elements. TPARS parses command lines by 
referencing a table that you define. You can build a state table, which contains states and 
transitions, by using the TPARS STATE$ and TRAN$ macros. A state delimits and represents 
a single syntax element on a command line. A transition is a statement that defines the 
processing required for parsing a given syntax element and contains instructions for further 
parsing at another state. TPARS uses subexpressions to resolve complex syntax elements. On 
the semantic level, TPARS also resolves the semantics or meaning of each element based on 
definitions supplied within action routines of your program. These action routines use TPARS 
macros, built-in variables, and your code to permit you to define and parse command lines. 


The parser routine that you write is included in your programs that parse command lines. 
TPARS is invoked from within an executing program by means of a CALL instruction. The 
CALL invokes the parser routine as well as the TPARS processor. For further information 
on the interrelationships among the calling program, the user-defined parser routine, and the 
TPARS processor, refer to Section 7.5. 


7.1 Coding TPARS Source Programs 


7.1. 


This section describes the three TPARS macros required to initialize and define the state table. 
Also included in this section is information describing action routines, TPARS built-in variables, 
and TPARS subexpressions. 


1 TPARS Macros—ISTAT$, STATE$, and TRANS 


TPARS provides macros that allow you to write a state table for parsing a unique command 
line. The ISTAT$ macro initializes a state table, the STATE$ macro defines a state (a particular 
syntax element) in your state table, and the TRAN$ macro defines the conditions for transition 
to another state. 
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7.1.1.1 ISTAT$ Macro—initialize the State Table 


ISTAT$ initializes the state table. The state table is built using two macros: STATE$ and 
TRANG, which are described in Sections 7.1.1.2 and 7.1.1.3, respectively. This state table is 
built into a program section. Keyword strings that you define for parsing command lines are 
also accumulated in a program section. A third program section is also provided for a keyword 
pointer table used to enter the list of keyword strings. The ISTAT$ macro initializes these 
program sections. 


A blank STATE$ macro must follow the TPARS state table. 


Format 
ISTAT$ __ statetable,keytable, $DEBUG 


Parameters 


statetable 
Specifies the label that you assign to the state table. TPARS recognizes this label as the 
start of the state table. 


keytable 
Specifies the label that you assign to the keyword table. TPARS recognizes this label as the 
start of the keyword table. 


SDEBUG 
Directs the assembler to list addresses of the state transition table in the assembly listing. 
These addresses are useful for tracing TPARS operation, using a debug routine that you 
supply (see Section 7.1.2.4). When you do not include $DEBUG, state transition table 
addresses are not listed. 


The state table is built in a program section named $STATE, the keyword strings are accumulated 
in a program section named $KSTR, and the keyword pointer table is built in a program section 
named $KTAB. 


If you define the symbol $RONLY, each of these program sections is generated as read-only. 
You generate a read-only state table by specifying the symbol $RONLY before the ISTAT$ 
macro in the following form: 


$RONLY = 1 
ISTAT$ statetable,keytable, $DEBUG 


STATES 


7.1.1.2 STATES Macro—Defining a Syntax Element 


STATE$ declares the beginning of a state. This macro delimits one command line syntax element 
from another. A blank STATE$ macro must follow the TPARS state table. 


Format 
STATE$ [label] 
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Parameter 


label 
Specifies an alphanumeric symbol that defines the address of the state. 


Each state defined by a STATE$ macro consists of any number of transitions defined by TRAN$ 
macros. The TRAN$ macros parse each syntax element. 


7.1.1.3 TRANS Macro—Defining a Transition 


The TRAN$ macro allows you to match each syntax element in a command line to a given 
type, to supply a symbolic address to the next TRAN$ macro, to supply an address of an action 
routine that may be required to further process the syntax element, and to supply a mask that 
you may use as a flag in the parsing process. 


Format 

TRAN$ type { ea \ [,action][,mask][|,maskaddr] 
Parameters 
type 


Specifies the type of command line syntax element being parsed. You code the type 
parameter by using one of the following types of command line elements: 


Element Type Description 

$ANY Matches any single character. 

$ALPHA Matches any single alphabetic character (A-Z). 

$DIGIT Matches any single digit (0-9). 

$LAMDA Matches an empty string. This transition is always successful. LAMDA 


transitions are useful for getting action routines called without passing 
any of the input string. 


$NUMBR Matches any number. A number consists of a string of digits; a 
concluding period is optional. Numbers not followed by a period are 
interpreted as octal. Numbers followed by a period are interpreted as 
decimal and the decimal point is included in the matching string. A 
number is terminated by any nonnumeric character. Values through 
2**32-1 are converted to 32-bit unsigned integers. 


$DNUMB Matches a decimal number. The string of digits is interpreted as 
decimal. With the exception that the matched string does not include 
the trailing decimal point, TPARS treats $DNUMB the same way it 
treats $NUMBR. 


$STRNG Matches any alphanumeric character string. The string will not be 
null. 
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Element Type Description 


$RAD50 Matches any legal Radix—50 string, that is, any string containing 
alphanumeric characters, or the period (.), or dollar sign ($) characters. 
If you require Radix-50 conversion, the action routine in your code 
must convert this number. 


$BLANK Matches a string of blank and/or tab characters. 


$EOS Indicates the position of the end of an input string. Once TPARS has 
reached the end of the input string, $EOS is the equivalent of that 
position as many times as $EOS is encountered in the state table. 


char Matches a single character in the syntax element whose American 
Standard Code for Information Interchange (ASCII) code corresponds 
to the value of char. The value of char must be a 7-bit ASCII code; 
that is, the value must be in the range 0-177,;. Specify a single 
quote (’) before char, such as ‘A or ’X. 


“keyword” Matches a specified keyword. Keywords can be any length, can contain 
only alphanumeric characters, must be in uppercase, and are terminated 
by the first nonalphanumeric character encountered in parsing the 
keyword. The maximum number of keywords allowed in a state table 
is 64. 


Nabei Matches the string processed by passing control to and executing the 
state table section that starts with a STATE$ macro that has the label 
parameter specified here as !label. In effect, this type of parameter 
passes control to a STATE$ macro subroutine or subexpression. For 
information on TPARS subexpressions, see Section 7.1.3. 


[label] 

[SEXIT] 
Specifies the label associated with a STATE$ macro to which execution control will pass 
after the code for this TRAN$ transition is executed. If the label parameter is omitted, 
execution control passes on to the next sequential STATE$ macro. A null label parameter is 
allowed only for the last transition in a state; a TRAN$ macro with a null label field must 
follow a TRAN$ macro. 


Specifying $EXIT in the label field terminates TPARS execution and returns control to the 
calling program. $EXIT also terminates a TPARS subexpression. 


action 
Specifies the label of an action routine that you include in the parser routine of your code. 
This routine can include TPARS built-in variables, described in Section 7.1.2.1. 


mask 
Specifies a mask word to be stored in a location pointed to by the mask-word address 
whenever the TRAN$ macro is executed. If you specify mask, you must specify the 
maskaddr parameter as well (see the following parameter). This mask word is ORed into 
maskaddr when the transition is taken (after the action routine is called). 
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maskaddr 
Specifies the label for an address into which TPARS stores the value specified by the mask 
parameter. You must specify the maskaddr parameter if you specify mask. 


The mask and maskaddr parameters provide a convenient means for flagging the execution 
of a particular transition. 


7.1.2 Action Routines and Built-In Variables 


Action routines process command line elements at the semantic level. That is, a given syntax 
element can have more than one meaning. Action routines determine and validate the meaning 
of the syntax elements. 


You write action routines in your parsing program to perform unique functions related to your 
program's requirements. 


7.1.2.1 TPARS Built-In Variables 
TPARS provides the following built-in variables for action routines: 


.PSTCN Returns the character count of the portion of the input string matched by this 
transition. This character count is valid for all syntax types recognized by TPARS, 
including subexpressions. 


.PSTPT Returns the address of the portion of the input string matched by this transition. 
This address is valid for all syntactical types recognized by TPARS, including 
subexpressions. 


-PNUMH _ Returns the high-order binary value of the number returned by a $NUMBR or 
$DNUMB syntax type specification. 


-PNUMB _ Returns the low-order binary value of the number returned by a $NUMBR or 
$DNUMB syntax type specification. 


.PCHAR Returns the character found by the $ANY, $ALPHA, $DIGIT, or char syntax type 
specifications. 


.PFLAG Returns the value of the flag word passed to TPARS by register 1 (R1). Action 
routines can modify this word to change options dynamically. 


.TPDEB Contains the entry address of the optional debug routine that you write. 

R3 Returns the byte count of the remainder of the input string. When the action 
routine is called, the string does not include the characters matched by the current 
transition. 

R4 Returns the address of the remainder of the input string. When the action routine is 


called, the string does not include the characters matched by the current transition. 


7.1.2.2 Calling Action Routines 


Action routines are called by a JSR PC (jump to subroutine program counter) instruction. Action 
routines may modify registers RO, R1, and R2; all other registers must be preserved. 
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7.1.2.3 Using Action Routines to Reject a Transition 


Action routines can reject a transition by returning to CALL+4 rather than to CALL+2. That is, 
the action routine performs the same function as an ADD #2,(SP) before returning to the caller. 
This technique allows additional processing of syntax types and extending of the syntax types 
beyond the set provided by TPARS. 


When an action routine rejects a transition, that transition has no effect. TPARS continues to 
attempt to match the remaining transitions in the state. 
7.1.2.4 Optional Debug Routine for RSX-11 Users 


A debug routine that you supply can be called by TPARS at each state transition, allowing the 
TPARS operation to be traced. For example, the routine can be written to display the contents 
of R5 each time the routine is called; R5 contains the current transition table address. You can 
monitor the TPARS operation by comparing the addresses displayed in the TPARS assembly 
listing, which shows the state transition table addresses. 


If a debug routine that you supply is to be called by TPARS, your task must first specify the 
entry point address for the debug routine in TPARS location .TPDEB, as follows: 


MOV #DENTER , . TPDEB 


Then, invoke TPARS with the .TPARD entry point (rather than with .TPARS). TPARS is invoked 
as described in Section 7.4. 


Upon entry to the debug program, central processing unit (CPU) registers contain the following: 
R3 __ Length of remainder of input string 

R4 Address of remainder of input string 

R5 —_ Current address of transition table 

The debug routine must save and restore all registers prior to returning to TPARS. 


For addresses displayed by the debug routine to be useful, you must obtain an assembly listing 
showing the addresses of the state transition tables. These addresses are listed by the assembler 
if the optional $DEBUG parameter is provided in the ISTAT$ macro call (see Section 7.1.1.1). 


7.1.3 TPARS Subexpressions 


A TPARS subexpression is a series of states and transitions analogous to a subroutine. In 
general, such a series of states and transitions is used more than once during the parsing 
process. 


Subexpressions begin with a STATE$ macro specifying the label of the subexpression. You 
follow this macro by the states and transitions that comprise the body of the subexpression. To 
terminate the subexpression, specify a TRAN$ macro with the $EXIT keyword specified in the 
label field. The general form of a subexpression is shown in the example that follows. 


In this example, control is directed to the subexpression by a TRAN$ macro that specifies a 
‘label syntax element as the type parameter, as follows: 


TRAN$ !UIC,NEXT 
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TPARS then directs control to the STATE$ macro with the label UIC, as follows: 


STATE$ UIC 
TRANS '[ 


STATE$ 
TRAN$ $NUMBR, ,SETGN 


STATE$ 
TRAN$ <',> 


STATES 
TRAN$ $NUMBR, ,SETPN 


STATE$ 
TRANS ') ,SEXIT 


When the User Identification Code (UIC) subexpression completes processing, control passes to 
the state labeled NEXT. 


7.2 General Coding Considerations 


Fin: 


This section contains information on how to arrange syntax types in a state table and how to 
direct TPARS to ignore blanks and table characters in a command line, and it provides rules for 
entering special characters (commas and angle brackets). 


1 Suggested Arrangement of Syntax Types in a State Table 


The transitions in a state may represent several syntax types; a portion of a string being scanned 
often matches more than one syntax type. Therefore, the order in which you enter the types in 
the state table is critical. Transitions are always scanned in the order in which they are entered, 
and the first transition matching a string being scanned is the transition taken. Therefore, the 
following order is recommended for states containing more than one syntax type: 


char 
keyword 
$EOS 
$ALPHA 
$DIGIT 
$BLANK 
$NUMBR 
$DNUMB 
$STRNG 
$RAD50 
$ANY 
$LAMDA 


Placement of ‘label transitions in a state depends on the types and positions of other syntax 
types in the state, as well as on the syntax types in the starting state of the subexpression. 
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7.2.2 Ignoring Blanks and Tabs in a Command Line 


Bit 0 of the low byte of register 1 (R1) controls processing of blanks and tab characters. If this 
bit is 1 when TPARS is invoked, blanks and tab characters are processed in the same way any 
other ASCII character is processed; they are treated as syntax elements that require validation 
by TPARS. If this bit is set to 0, blanks and tab characters are interpreted as delimiter characters; 
they are ignored as syntax elements. In neither case does TPARS modify the command line. 


When blanks are being ignored, the $BLANK syntax type never matches an element on the 
command line. Also, when this option is in effect, values returned to the !label syntax type 
by .PSTCN or .PSTPT may contain blanks or tabs, even though none were requested. The 
examples that follow show how TPARS parses the following string: 


ABC DEF 
The parsing may occur with and without the blank-suppress option. 


In the following example, an extra state is required to parse the blank: 


STATE$ 
TRAN$ S$STRNG 
STATE$ 
TRAN$ $BLANK 
STATE$ 
TRAN$ $STRNG 


When TPARS is directed to ignore blanks and tab characters, the same string can be parsed 
using only two states, as follows: 


STATE$ 
TRANS $STRNG 
STATE$ 
TRANS $STRNG 


7.2.3 Entering Special Characters 


In char syntax elements, MACRO-11 interprets commas (,), semicolons (;), and angle brackets 
(< >) as special characters. The comma is interpreted as an argument separator and angle 
brackets are used to enclose special characters in parentheses. 


To include a comma or a semicolon in a char syntax element string, use angle brackets as 
follows: 


TRAN$ <',> 


Angle brackets cannot be passed as string elements in macro arguments. If required in a “char” 
expression, they must be expressed symbolically. For example: 


LA = '< 
TRAN$ LA 
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7.2.4 Recognition of Keywords 


When TPARS encounters a transition table entry that specifies a keyword, it first scans from 
the current point in the input string in search of a delimiter (nonalphanumeric) character. The 
characters between the current input point and the next delimiter are then assumed to be a 
possible keyword and are matched against the entries in the keyword table. For this reason, 


the following example will not work as expected: 


STATES 

TRAN$ “NO",STATE1,SETNEG 
TRAN$ $LAMDA,,SETPOS 
STATE$ STATE1 

TRANS "AA",... 

TRAN$ "BB",... 


When TPARS encounters the keyword NO, it scans and attempts to match the string “NOAA” 
or “NOBB”. If exact matching is requested, neither the “NO” transition nor the “AA” transition 
will match. In addition, if keyword matching is limited to two characters, the “NO” transition 
will match but TPARS will skip past “NOAA” so that the “AA” transition can be taken. You 
can use the following example to achieve the desired operation: 


STATES 

TRANS !NONO ,STATE1 , SETNEG 
TRAN$ $LAMDA, ,SETPOS 
STATE$ STATE 

TRANS "AA",... 

TRAN$ "BB",... 

STATE$ NONO 

TRANS 'N 

STATES 

TRAN$ 'O, $EXIT 


In this example, TPARS attempts to match the subexpression NONO to the “NO” prefix one 
character at a time. This attempt bypasses the keyword scanning of TPARS, allowing the input 
pointer to be left pointing at “AA” or “BB”. If NONO fails, the input pointer will not be changed 


and the scan can continue by looking for “AA” or “BB”. 


7.3 Program Sections Generated by TPARS Macros 


TPARS macros generate three program sections. Data for the STATE$ macro are stored in the 
program section $STATE; whereas, data for the TRAN$ macro are stored in program sections 
$KSTR and $KTAB. The program section $KTAB contains addresses for each of the entries of 
the keyword syntax type. $KSTR contains the keyword entries separated by character code 


3773. 
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Each state consists of its transition entries concatenated in the order in which you specify them. 
The state label, if specified, is equated to the address of the first transition in the state. Each 
transition consists of from one to six words, as follows: 


ZK-314-81 


The type byte of the first word may contain the following values: 


Spurn nn 


Type 
Byte 


Value 


a 


$LAMDA 
$NUMBR 
$STRNG 
$BLANK 
$SUBXP 
$EOS 
$DNUMB 
$RAD50 
$ANY 
$ALPHA 
$DIGIT 
char 


keyword 


306 

310 (Used in the !label type.) 

312 

314 

316 

320 

322 

324 

ASCII code for the specified character 
200+n (See the explanation that follows.) 


The value of keyword is 200+n, where n is an index into the keyword table. The keyword 
table is an array of pointers to keyword strings, which are stored in the program section $KSTR. 
Keyword strings in $KSTR are separated from each other by 3773. 
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Bits in the flags byte indicate whether parameters for the TRAN$ macro are specified as follows: 


Bit Meaning 

Type extension is specified. 
Action routine label is specified. 
Target state label is specified. 
Mask word is specified. 


Mask-word address is specified. 


N *#& © NY HF O&O 


Indicates last transition in the current state. 


7.4 Invoking TPARS 


You control execution of TPARS by using the calling conventions and options described in 
this section. You invoke TPARS from within an executing program by using the following 
instruction: 


CALL . TPARS 


When a debug routine that you specify traces a TPARS operation (see Section 7.1.2.4), a special 
entry point is called, as follows: 


CALL . TPARD 
When your task calls TPARS in this manner, TPARS calls the debug routine at each state 
transition. If your task invokes TPARS by the .TPARS entry point, the debug routine entry 
point address in .TPDEB is cleared and the debug routine is not called. 
7.4.1 Register Usage and Calling Conventions 
When TPARS is invoked, registers in the calling program must contain the following information: 
R1 Options word 
R2 Pointer to the keyword table 
R3 Length of the string to be parsed 
R4 Address of the string to be parsed 
R5 Label of the starting state in the state table 
On return from TPARS processing, registers contain the following information: 
R3 Length of the unscanned portion of the string 
R4 Address of the unscanned portion of the string 
The values of all other registers are preserved. 


The Carry bit in the Processor Status Word (PSW) returns 0 for a successful parse; the Carry 
bit is set when TPARS finds a syntax error. 


For an example of a calling sequence for TPARS, refer to Section 7.6.1. 
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7.4.2 Using the Options Word 


The low byte of the options word contains flag bits. The only flag bit defined is bit 0, which 
controls processing of blanks. If bit 0 is set to 1, blanks are interpreted as syntax elements. If 
bit 0 is set to 0, blanks are ignored as syntax elements but are still processed as delimiters. 


The high byte of the options word controls abbreviation of keywords. If the high byte is set to 
0, keywords being parsed must exactly match their corresponding entries in the state table. If 
the high byte is set to a number, keywords being parsed may be abbreviated to that number of 
characters. 


TPARS clears the Carry bit in the PSW when it completes processing successfully. This occurs 
when a transition is made to $EXIT that is not within a subexpression. 


If a syntax error occurs, TPARS sets the Carry bit in the PSW and terminates. 


A syntax error occurs when there are no syntax elements in the current state that match the 
portion of the string being scanned. Illegal type codes and errors in the state table can also 
cause a syntax error. 


TPARS processing requires that the addresses in the state table and the keyword tables be 
reliable; bad addresses may cause program termination. 


The only syntax types that can match the end of the string are $EOS and $LAMDA. 


7.5 How to Generate a Parser Program Using TPARS 


Three processing steps generate a parser program using TPARS, as shown in Figure 7-1. The 
source program must contain .MCALL statements for three macros: ISTAT$, STATE$, and 
TRAN$. These three .MCALL statements must precede the statements that comprise the state 
table and action routines. 


Assembling the source module produces an object module composed of three program sections. 
The assembly listing showing the code produced by the state table macros is not straightforward. 
The binary output of the macros is delayed by one statement. Thus, if you enable the listing 
of macro-generated binary code during assembly of the code, the binary code appearing after 
a macro call is, in fact, the result of the preceding macro call. Error messages generated by 
macro calls are similarly delayed. This is the reason an additional STATE$ macro is required to 
terminate the state table. 


When the parser program is linked and is in task image form, it can be invoked from within 
your executing task, as shown in Figure 7-1. 


Figure 7-2 shows the CALL .TPARS statement that invokes the parser program and the TPARS 
processor. As the parser executes the state table, it calls action routines. These action routines 
access code in the TPARS processor to perform such functions as returning the values of the 
built-in variables. When the state table completes execution, TPARS receives control and passes 
control back to the calling program. 
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Figure 7-1: Processing Steps Required to Generate a Parser Program Using TPARS 


PARSER.SRC 


MCALL ISTATS 


Le Write a source program that MCALL STATES 
~~ ----- > includes the required MCALL ae? MCALL TRANS 
statements. STATES 


STATES 


PARSER.OBJ 


co 
cs 


MACRO-11 


2. Assemble the source program to 
produce an object module. —— $KTAB 


PARSER.SRC 


PARSER.OBJ 


MYFILE.TSK 


3. Execute the Task Builder to = 
produce a task image including 


the parser. 


MY FILE.OBJ 


ae 


De Se 
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<> 
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Figure 7-2: Flow of Control When TPARS Is Called from an Executing User Program 


Executing User-Defined TPARS 
User Program Parser Program Processor 


STATE$ 


* 


* 


STATE$ 


CALL.TPARS 
Routines 


7.6 Programming Examples 


This section includes three programming examples of how TPARS can be used in your program. 
The first example shows the code required to parse a User File Directory (UFD) command line 
for RSX-11. The second example shows the use of subexpressions and how to reject transitions. 
The third example shows how to use subexpressions to parse complex command lines. 

7.6.1 Parsing a UFD Command Line 


This example shows the code required to parse a UFD command line. It includes a state table 
and action routines. The general form of the UFD command line is as follows: 


UFD DUO:LABEL[201 ,202] /ALLOC=100 . /PRO=[RWED , RWED , RWE, R]} 


7-14 The Table-Driven Parser (TPARS) 


The action routines in this parser program return the following values: 


Action Routine Value 


$UDEV Device name (two ASCII characters) 
$UUNIT Unit number (binary) 

$UVNML Byte count of the volume label string 
$UVNAM Address of the volume label string 
$UUIC Binary UIC for which to create a directory 
$UALL Number of directory entries to preallocate 
$UPRO Binary protection word for UFD 

$FLAGS Flags word containing the following bits: 


UF.ALL Set if allocation was specified. 
UF.PRO Set if protection was specified. 


i 


The label and the /ALLOC and /PRO switches are optional. The calling sequence for this 


routine is as follows: 

CLR R1 

MOV #UFDKTB,R2 

MOV COUNT,R3 

MOV ADDR,R4 

MOV #START,R5 

CALL .TPARS 

BCS ERROR 

The following is an example of the parser routine that you write: 
.TITLE STATE TABLE FOR UFD COMMAND LINE 
.MCALL ISTAT$,STATE$, TRANS 

; TO BE USED WITH BLANK SUPPRESS OPTION 
ISTAT$ UFDSTB,UFDKTB 

; READ OVER COMMAND NAME 
.GLOBL START 


STATE$ START 
TRAN$ "“UFD" 


; READ DEVICE AND UNIT NUMBER 


STATE$ 
TRAN$ $ALPHA, ,SETDV1 


STATE$ 
TRAN$ $ALPHA, ,SETDV2 
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STATES 
TRAN$ $NUMBR,DEV1,SETUNT 
TRAN$ $LAMDA 


STATE$ DEV1 
TRANS aA 


; READ VOLUME LABEL 


STATE$ 
TRAN$ $STRNG,RUIC ,SETLAB 
TRAN$  $LAMDA 


; READ UIC 


STATE$ RUIC 
TRANS !UIC 


; SCAN FOR OPTIONS AND END OF LINE 


STATE$ OPTS 
TRAN$ $EOS,$EXIT 
TRANS / 


STATES 
TRAN$ “ALLOC",ALC, ,UF.ALL,$FLAGS 
TRANS "PRO" ,PRO, ,UF.PRO,$FLAGS 

; SET ALLOCATION 


STATE$ ALC 
TRANS ‘= 


STATE$ 
TRAN$ $NUMBR,OPTS ,SETALC 


; PROTECTION 


STATE$ PRO 
TRANS = 


STATE$ 
TRAN$ '{,, IGROUP 


STATE$ SPRO 

TRANS '] ,OPTS , ENDGRP 
TRAN$ <',>,SPRO,NXGRP 
TRAN$ 'R,SPRO,SETRP 
TRANS 'W,SPRO , SETWP 
TRANS 'E,SPRO ,SETEP 
TRANS 'D,SPRO ,SETDP 


; SUBEXPRESSION TO READ AND STORE UIC 


STATE$ UIC 
TRAN$ ='[ 


STATE$ 
TRANS $NUMBR, ,SETGN 


STATE$ 
TRAN$ <',> 


STATES 
TRANS $NUMBR, ,SETPN 


STATE$ 
TRAN$ '),$EXIT 
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; STATE TABLE SIZ 
; KEYWORD TABLE § 
; KEYWORD POINTER 


-SBITL 
; DEVICE NAME CHA 
SETDV1: : MOVB 


; DEVICE NAME CHA 
SETDV2: : MOVB 


; UNIT NUMBER 
SETUNT: : MOV 


; VOLUME LABEL 
SETLAB: : MOV 


; PPN - GROUP NUM 
SETGN: : 


STATE$ 


E: 60 WORDS 
IZE: 8 WORDS 
SPACE: 3 WORDS 


ACTION ROUTINES FOR THE COMMAND LINE PARSER 
Ri 


. PCHAR , $UDEV 
RETURN 


R 2 


. PCHAR , SUDEV+1 
RETURN 


. PNUMB , SUUNIT 
RETURN 


-PSTCN, $UVNML 


MOV .PSTPT , $UVNAM 
RETURN 

BER 
MOVB . PNUMB , $UUIC+1 
BR TSTPPN 


; PPN - PROGRAMMER NUMBER 


SETPN: : 
TSTPPN : 


10$: 
20$: 


; NUMBER OF ENTRI 
SETALC: : MOV 


; SET PERMISSIONS 
; INITIALIZE 


IGROUP : : MOV 
; MOVE TO NEXT PE 
NXGRP: : 


BADGRP: 
30$: 


; SET READ PERMIT 


MOVB . PNUMB , $UUIC 


TST . PNUMH ; CHECK FOR O HIGH ORDER 
BNE 10$ 

TSTB - PNUMB+1 ; CHECK FOR BYTE VALUE 
BEQ 20$ 

ADD #2, (SP) ; BAD VALUE - REJECT TRANSITION 
RETURN 
ES TO ALLOCATE 

. PNUMB ,, $UALL 

RETURN 

#4 ,GRCNT 
RMISSIONS CATEGORY 

SEC ; FORCE ONES 

ROR $UPRO 

ASR $UPRO ; SHIFT TO NEXT GROUP 

ASR $UPRO 

ASR SUPRO 

DEC GRCNT ; COUNT GROUPS 

BGE 30$ ; TOO MANY IS AN ERROR 

ADD #2, (SP) ; IF SO, REJECT TRANSITION 
RETURN 
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SETRP: : BIC 


RETURN 


; SET WRITE PERMIT 


SETWP: : BIC 


RETURN 


; SET EXTEND PERMIT 


SETEP: : BIC 


RETURN 


; SET DELETE PERMIT 


SETDP: : BIC 


RETURN 


; END OF PROTECTION SPEC 


ENDGRP : : TST GRCNT 


BNE 
RETURN 


. END 


#FP .RDV*10000, $UPRO 


#FP .WRV*10000, $UPRO 


#FP . EXT*10000 , $UPRO 


#FP .DEL*10000 , $UPRO 


; CHECK THE GROUP COUNT 
BADGRP ; MUST HAVE 4 


UFD 


7.6.2 Using Subexpressions and Rejecting Transitions 


The following example is an excerpt from a state table that parses a string in which the first 
character is interpreted as a quote character. This typical construction occurs in many editors 
and programming languages. The action routines associated with the state table return the byte 
count and address of the string in the locations QSTC and QSTP. The quoting character is 
returned in location QCHAR. 


; MAIN LEVEL STATE TABLE 


STATE$ 
TRANS 
ACCEPT THE QUOTED STRING 


STATES 
TRANS 
GOBBLE UP THE TRAILING Q 


STATE$ 
TRANS 


; PICK UP THE QUOTE CHARACTER 


STRING 
SANY, ,SETQ 


!QSTRG, ,SETST 
UOTE CHARACTER 


$ANY , NEXT , RESET 


SUBEXPRESSION TO SCAN THE QUOTED STRING 


THE FIRST TRANSITION WIL 
BY THE ACTION ROUTINE 


STATE$ 
TRAN$ 
TRANS 
STATES 


ACTION ROUTINES 


LL MATCH UNTIL IT IS REJECTED 


QSTRG 
$ANY ,QSTRG, TESTQ 
$LAMDA , $EXIT 


STORE THE QUOTING CHARACTER 
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SETQ: MOVB . PCHAR , QCHAR 


INCB . PFLAG ; TURN OFF SPACE FLUSH 
RETURN 
; TEST FOR QUOTING CHARACTER IN THE STRING 
TESTQ: CMPB . PCHAR , QCHAR 
BNE 10$ 
ADD #2, (SP) ; REJECT TRANSITION ON MATCH 
10$: RETURN 
; STORE THE STRING DESCRIPTOR 
SETST: MOV . PSTPT , QSTP 
MOV - PSTCN , QSTC 
RETURN 
; RESET THE SPACE FLUSH FLAG 
RESET: DECB . PFLAG 
RETURN 


7.6.3 Using Subexpressions to Parse Complex Command Lines 


The following excerpt from a state table shows how subexpressions are used to parse complex 
command lines. 


The state table accepts a number followed by a keyword qualifier. Depending on the keyword, 
the number is interpreted as either octal or decimal. The binary value of the number is returned 
in the tagged NUMBER. The following types of strings are accepted: 


10/OCTAL 
359/DECIMAL 
77777/OCTAL 


; MAIN STATE TABLE ENTRY - ACCEPT THE EXPRESSION AND 
; STORE ITS VALUE 


STATES 
TRAN$ !ONUMB , NEXT , SETNUM 
TRAN$ !DNUMB , NEXT , SETNUM 


; SUBEXPRESSION TO ACCEPT OCTAL NUMBER 


STATE$ ONUMB 
TRAN$ $NUMBR 


STATE$ 
TRAN$ '/ 


STATES 
TRAN$ "OCTAL" ,$EXIT 


; SUBEXPRESSION TO ACCEPT DECIMAL NUMBER 


STATE$ DNUMB 
TRAN$ $DNUMB 


STATE$ 

TRANS '/ 

STATE$ 

TRAN$ "DECIMAL", $EXIT 
STATES 


The Table-Driven Parser (TPARS) 7-19 


; ACTION ROUTINE TO STORE THE NUMBER 


SETNUM: MOV . PNUMB , NUMBER 
MOV . PNUMH , NUMBER+2 
RETURN 


The contents of .PNUMB and .PNUMH remain undisturbed by all state transitions except the 
$NUMBR and $DNUMB types. 


Because of the way in which subexpressions are processed, calls to action routines from within 
subexpressions must be handled with care. 


When a subexpression is encountered in a transition, TPARS saves its current context and calls 
itself, using the label of the subexpression as the starting state. If the subexpression parses 
successfully and returns by means of $EXIT, the transition is taken and control passes to the 
next state. If the subexpression encounters a syntax error, TPARS restores the saved context 
and tries to take the next transition in the state. 


However, TPARS provides no means for resetting original values changed by action routines 
that were called by subexpressions. Therefore, action routines called from subexpressions should 
store results in an intermediate area. Data in this intermediate area can then be accessed by an 
action routine called from the primary level of the state table. 
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Chapter 8 
Spooling 


File Control Services (FCS) provides facilities at both the macro and subroutine level to queue 
files for subsequent printing. As a result, your task can queue a print job. There are several 
ways for your task to spool output for printing; however, you cannot control the printing from 
within your task as you can with the Digital Command Language (DCL) command PRINT. You 
can, however, use the DCL command SET QUEUE (Monitor Console Routine (MCR) command 
QUE /MOD) to alter the attributes of the print job once the job appears in the queue. 


8.1 PRINTS Macro 


A task issues the PRINT$ macro to queue a file for printing on a specified device. The specified 
device must be a unit record, carriage-controlled device such as a line printer or terminal. The 
file is placed in the default queue PRINT. If the device is not specified, LP is used. 


The file to be spooled must be open when the PRINT$ macro is issued. Once the file is queued, 
PRINT$ closes the file. Error returns differ from normal FCS conventions. Refer to Section 8.3 
for more information. 


Format 
PRINT$ _ fdb,err 


Parameters 


fdb 
Specifies the address of the associated File Descriptor Block (FDB). This parameter need not 
be present if the address of the associated FDB is already in RO. 


err 
Specifies the address of an optional, error-handling routine that you code. See Section 8.3 
for more information. 
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8.2 .PRINT Subroutine 


8.2. 


Your task can open a file on disk, send output to the disk, and close the file either by using 
the PRINT$ macro call or by calling the .PRINT subroutine to spool the output. The .PRINT 
subroutine is called to queue a file for printing. Before your task can call PRINT, RO must 
contain the address of the associated FDB and the file must be open. Next, the file is placed in 
the default queue PRINT and the .PRINT routine closes the file. One copy of the file is printed 
on the LP device. In your task, it may be preferable to call the .PRINT subroutine if the routine 
resides in FCSRES. Using the PRINT$ macro causes all the code of .PRINT to appear in your 
task each time it is used. 


Section 8.3 describes error handling for the .PRINT file control routine. 


1 Opening a File on Disk and Using the PRINT Command 


As stated in the opening of this section, your task can open a file on disk, send output to that 
disk, and close the file. When the task exits, the PRINT command can print the file. This is 
the only method that gives you access to the PRINT command qualifier. Other than using the 
qualifier, your task can use PRINT$ or .PRINT; you then wait until the job is in the queue and 
alter its attributes with the DCL command SET QUEUE (MCR command QUE /MOD). 


If you run your task from an indirect command file or batch job that includes a PRINT command 
after the task exits, the difference between spooling from within a task or from outside it is 
negligible. 


Note that you can use the SPWN$ directive in the task to issue the PRINT command. (Refer 
to the RSX-11M-PLUS and Micro/RSX Executive Reference Manual.) 


8.2.2 Opening a File on LP 


Your task can use the OPEN$ macro to name the output device. FCS opens the file on pseudo 
device SP0:. The file is placed in the device-specific queue for the device you named. When 
your task has finished writing to this file, close it with a CLOSE$ macro. The file is deleted after 
it is printed. This file does not remain in any directory but is identified by a file-ID number 
labeled FID in the SHOW QUEUE display. 


8.3 Error Handling 
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The error returns provided with PRINT$ and .PRINT differ from the standard FCS error returns. 
Unlike FCS error returns, PRINT$ and .PRINT error codes are placed in F.ERR or in the Directive 
Status Word (DSW), depending on when the failure occurred. 


If the failure is FCS related (for example, the PRINT$ macro cannot close the file), the Carry 
bit is set and F.ERR contains the error code. If the failure is related to the SEND/REQUEST 
directive that queues the file, the Carry bit is set and the DSW contains an error code. DSW 
error codes are listed in the RSX-11M-PLUS and Micro/RSX Executive Reference Manual. 


Normally, once you determine that the Carry bit is set, any error routine that you code should 
first test FLERR and then test the DSW error code. 
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Appendix A 
File Descriptor Block 


A File Descriptor Block (FDB) contains file information that is used by File Control Services 
(FCS) and the file control primitives. Figure A-1 displays the layout of the FDB. 
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Figure A-1: File Descriptor Block Format 


File-Attribute Section 


F.RATT 1 Record Attributes Record Type 0 F.RTYP 
Highest Virtual Block Number Allocated 4 F.HIBK 
End-of-File Block Number 10 F.EFBK 
First Free Byte in Last Block 14 F.FFBY 
Record- or Block-Access Section 
er ouCatel 16 FRACC 
Block 1/O Buffer Descriptor 20 F.BKDS 
User’s Record Buffer Descriptor 20 F.URBD 
Next Record Buffer Descriptor 24 F.NRBD 
Block 1/O Status Block Address 24 F.BKST 
Block I/O Done AST Address 26 F.BKON 
Override Block Buffer Size 30 F.OVBS 
Next Record Address in Block Buffer 30 F.NREC 
End-of-Biock Buffer 32 F.EOBB 
Record Number for Random Records 34. F.RCNM 


mee eee eee ae i Oe ee es ee 


Size in Blocks of Contiguous File 


Address to Read in Statistics Block 


34 F.CNTG 
36 =F.STBK 


Z2K-3010/1-84 


(Continued on next page) 
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Figure A-1 (Cont.): File Descriptor Block Format 


File-Open Section 


F.FACC Logical Unit Number F.LUN 


Block-Buffer Section 


Bookkeeping Bits QIO Event Flag 


F.BKP1 51 50 ~F.EFN or F.BKEF 


Block 1/O Virtual Block Number 64 F.BKVB 
Virtual Block Number 64 F.VBN 
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Note that each section within the FDB contains symbolic offset names and each offset’s location. 
You can define an FDB offset name locally or globally. To define an offset locally, use either of 
the following macro calls: 


FDOF$L 


;DEFINE OFFSETS LOCALLY. 


FDOFF$ DEF$L ; DEFINE OFFSETS LOCALLY. 


To define an FDB offset name globally, use the following macro call: 


FDOFF$ DEF$G ;DEFINE OFFSETS GLOBALLY. 


Note 


When you refer to FDB locations, it is essential to use the symbolic offset names 
rather than the actual address of such locations. The position of information 
within the FDB may be subject to change from version to version; whereas, the 
offset names remain constant. 


Table A-1 describes the offset locations within the FDB. 


Table A-1: 


Symbolic 
Offset 
Name 


F.RTYP 


F.RATT 


F.RSIZ 


F.HIBK 


FDB Offset Definitions 
Size 
(Bytes) Contents 


1 This byte is set, as follows, to indicate the type of records for the file: 
F.RTYP = 1 Indicates fixed-length records (R.FIX). 


F.RTYP = 2 Indicates variable-length records (R.VAR). 
F.RTYP = 3 Indicates sequenced records (R.SEQ). 


1 Bits 0 to 3 are set to indicate record attributes, as follows: 


BitO=1 Indicates that the first byte of a record is to contain a FORTRAN 
carriage control character (FD.FTN); otherwise, it is 0. 


Bit 1 = 1 Indicates, for a carriage control device, that a line feed is to be 
performed before the line is printed and a carriage return is to 
be performed after the line is printed (FD.CR); otherwise, it is 
0. 


Bit2=1 Indicates the “print file format” (FD.PRN). FCS allows this 
attribute but does not interpret the format word. 


Bit3=1 Indicates that records cannot cross block boundaries (FD.BLK); 
otherwise, it is 0. 


2 This location contains the size of fixed-length records or indicates the size of 
the largest record that currently exists in a file of variable-length records. 


4 Indicates the highest virtual block number allocated. 
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Table A-1 (Cont.}: FDB Offset Definitions 


Symbolic 
Offset 
Name 


F.EFBK 


F.FFBY 


F.RACC 


F.RCTL 


F.BKDS 
or 
F.URBD 


F.NRBD 


Size 
(Bytes) 


4 


Contents 


Contains the end-of-file (EOF) block number. 


The format of the block number is high-order word followed by low-order 
word. 


Indicates the first free byte in the last block or the maximum block size for 
magnetic tape. 
Bits 0 to 3 of this byte define the record access modes, as follows: 


Bit 0 = 1 Indicates READ$/WRITE$ mode (FD.RWM); otherwise, it is 0 
to indicate GET$/PUT$ mode. 


Bit 1=1 Indicates random access mode (FD.RAN) for GET$/PUT$ record 
I/O; otherwise, it is 0 to indicate sequential access mode. 


Bit 2=1 Indicates locate mode (FD.PLC) for GET$/PUT$ record I/O; 
otherwise, it is 0 to indicate move mode. 


Bit3=1 Indicates that PUT$ operation in sequential mode does not 
truncate the file (FD.INS); otherwise, it is 0 to indicate that 
PUT$ operation in sequential mode truncates the file. 


Bits 0 to 5 define the characteristics of the device associated with the file, as 
follows: 


Bit 0=1 Indicates a record-oriented device (FD.REC), for example, a 
teletypewriter or line printer; a value of 0 indicates a block- 
oriented device, for example, a disk or DECtape. 


Bit 1=1 Indicates a carriage control device (FD.CCL); otherwise, it is 0. 
Bit 2=1 Indicates a teleprinter device (FD.TTY); otherwise, it is 0. 
Bit 3=1 Indicates a directory device (FD.DIR); otherwise, it is 0. 


Bit 4=1 Indicates a single directory device (FD.SDI). A Master File 
Directory (MFD) is used, but no User File Directories (UFDs) 
are present. 


Bit5=1 Indicates a block-oriented device that is inherently sequential 
in nature (FD.SQD), such as magnetic tape. A record-oriented 
device is assumed to be sequential in nature; therefore, this bit 
is not set for such devices. 


Contains the block I/O buffer descriptor. 


Contains the user record buffer descriptor. 


Contains the next record buffer descriptor. The record buffer descriptor 
contains the size of the buffer in the first word and the address of the buffer 
in the second word. 
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Table A-1 (Cont.): FDB Offset Definitions 


Symbolic 

Offset Size 

Name (Bytes) Contents 

or 

F.BKST 2 Contains the address of the I/O status block (IOSB) for block I/O. 

and 

F.BKDN 2 Contains the address of the asynchronous system trap (AST) service routine 
for block I/O. 

F.OVBS 2 This field has meaning only before the file is opened. 

or 

F.NREC 2 Contains the address of the next record in the block. 

F.EOBB 2 Contains a value defining the end-of-block buffer. 

F.RCNM 4 Contains the number of the record for random access operations. The format 
of the record number is the high-order word followed by the low-order word. 

or 

F.CNTG 2 Contains a numeric value defining the number of blocks to be allocated in 
creating a new file. This cell has meaning only before the file is opened. 

and A value of 0 means leave the file empty; a positive value means allocate 
the specified number of blocks as a contiguous area and make the file 
contiguous; a negative value means allocate the specified number of blocks 
as a noncontiguous area and make the file noncontiguous. 

F.STBK 2 Contains the address of the statistics block in your program. 

F.ALOC 2 Contains the number of blocks to be allocated when the file must be extended. 
A positive (+) value indicates contiguous extend, and a negative (-) value 
indicates noncontiguous extend. 

F.LUN 1 Contains the logical unit number associated with the FDB. 

F.FACC 1 This byte indicates the access privileges for a file, as follows: 


Bit 0=1 If the file is accessed for reading only (FA.RD). 
Bit 1 = 1 If the file is accessed for writing (FA.WRT). 
Bit 2=1 If the file is accessed for extending (FA.EXT). 


Bit 3 = 1 If a new file is being created (FA.CRE); otherwise, i is 0 to 
indicate an existing file. 


Bit 4= 1 If the file is a temporary file (FA.TMP). 
Bit5=1 If the file is opened for shared access (FA.SHR). 


If Bit 3 equals 0, then the following is true: 
Bit6=1 If an existing file is being appended (FA.APD). 
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Table A-1 (Cont.): FDB Offset Definitions 


Symbolic 
Offset Size 
Name (Bytes) Contents 
If Bit 3 equals 1, then the following is true: 
Bit6=1 If not superseding an existing file at file-create time (FA.NSP). 
F.DSPT 2 Contains the data-set descriptor pointer. 
F.DFNB 2 Contains the default filename block pointer. 
F.BKEF 1 Contains the block I/O event flag. 
or 
F.EFN Contains the record I/O event flag. 
F.BKP1 1 Contains bookkeeping bits for FCS internal control. 
F.ERR 1 A negative value indicates an error condition. 
F.ERR+1 1 Used in conjunction with F.ERR. If F.ERR is negative, the following applies: 
F.ERR+1 = 0 Indicates that the error code is an I/O error code 
(see error codes in Appendix K). 
F.ERR+1 = negative value _Indicates that the error code is a Directive Status 
Word (DSW) error code (see DRERR$ error 
codes in Appendix K). 
F.MBCT 1 Indicates the number of buffers to be used for multibuffering. 
F.MBC1 1 Indicates the actual number of buffers currently in use if the multibuffering 
version of FCS is in use. 
F.MBFG 1 Contains either one of the multibuffering flags, as follows: 


Bit 0 = 1 Indicates read-ahead (FD.RAH). 
Bit 1 = 1 Indicates write-behind (FD.WBH). 


F.BGBC 1 Indicates big-buffer block count in number of blocks if the big-buffer version 
of FCS is in use. 


Buffer offset for reading ANSI magnetic tape in record mode. 


F.VBSZ 2 Contains the virtual block size (in bytes). 
F.BBFS 2 Indicates the block buffer size. 
F.BKVB 4 Contains the virtual block number in the user program for block I/O. 
or 
F.VBN Contains the virtual block number. The format of the virtual block number 


is the high-order word followed by the low-order word. 


F.BDB 2 Contains the address of the block buffer descriptor block. This location 
always contains a nonzero value if the file is open and a zero value if the 
file is closed. 
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Tabie A-1 (Cont.): 


Symbolic 
Offset 
Name 


F.EXT 
F.FLG 
F.CHR 


F.ACTL 


Size 
(Bytes) 


2 
1 
1 


2 


FDB Offset Definitions 


Contents 


Address of FDB extension. 


Flag byte. 


The control bit is defined as follows: 


Bit 0 = 1 


Indicates ANSI magnetic tape formats D or F. 


The low-order byte of this word indicates the number of retrieval pointers 
to be used for the file. The control bits are in the high-order byte and are 
defined as follows: 


Bit 15 =1 
Bit 12 = 0 
Bit 12 = 1 
Bit 11 =1 
Bit9=1 


Specifies that control information is to be taken from F.ACTL 
(FA.ENB). 


Causes positioning to the end of a magnetic tape volume set 
upon open or close. 


Causes positioning of a magnetic tape volume set to just past 
the most recently closed file when the next file is opened 
(FA.POS). 


Causes a magnetic tape volume set to be rewound upon open 
or close (FA.RWD). 


Causes a file to be unlocked if it is not properly closed when 
accessed for write (FA.DLK). 


Contains the sequence number for sequenced records. 


The symbolic offset of the beginning of the filename block portion of the 


FDB. 
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Appendix B 
Filename Block 


A filename block is the portion of the File Descriptor Block (FDB) that contains the various 
elements of a file specification used by File Control Services (FCS). The format of a filename 
block is illustrated in Figure B-1. 
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Figure B-1: Filename Block Format 


Cumulative 
Length in 
Bytes (Octal) 


2K-301-81 


Offset names in a filename block may be defined either locally or globally. You can define an 
offset name locally by using either of the following macro calls: 


NBOF$L ;DEFINE OFFSETS LOCALLY. 
NBOFF$ DEF$L ;DEFINE OFFSETS LOCALLY. 


To define an offset name globally, use the following macro call: 


NBOFF$ DEF$G ;DEFINE OFFSETS GLOBALLY. 


Note 


When you refer to filename block locations, it is essential to use the symbolic 
offset names rather than the actual addresses of such locations. The position 
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of information within the filename block may change from release to release; 
whereas, the offset names remain constant. 


The offset names in a filename block are described in Table B-1. 


Table B-1: 


Symbolic 
Offset 
Name 


N.FID 
N.FNAM 


N.FTYP 


N.FVER 
N.STAT 
N.NEXT 
N.DID 
N.DVNM 
N.UNIT 


Filename Block Offset Definitions 


Size 


(Bytes) 
6 


Contents 
File identification field 


File name field; specified as nine characters that are stored in 
Radix-50 format 


File type field; specified as three characters that are stored in 
Radix-50 format 


File version number field (binary) 

Filename block status word (See bit definitions in Table B-2.) 
Context for next .FIND operation 

Directory identification field 

ASCII device name field 

Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) in the FDB and their significance 
are described in Table B—2. (Other bits are set as required by FCS and the Peripheral Interchange 
Program (PIP) for processing.) 


Table B-2: 


Symbolic 
Offset 
Name 


NB.VER! 
NB.TYP? 
NB.NAM! 
NB.SVR 
NB.STP 
NB.SNM 
NB.DIR! 


Filename Block Status Word (N.STAT) 


Value 
(Octal) 


1 
2 


Meaning 

Set if explicit file version number is specified. 
Set if explicit file type is specified. 

Set if explicit file name is specified. 

Set if wildcard file version number is specified. 
Set if wildcard file type is specified. 

Set if wildcard file name is specified. 


Set if explicit directory string User Identification Code (UIC) is 
specified. 


lindicates bits that are set if the associated information is supplied through an ASCII data-set descriptor. 
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Table B-2 (Cont.): 


Symbolic 
Offset 
Name 
NB.DEV! 
NB.SD1? 
NB.SD2? 
NB.ANS 


NB.WCH 


Value 
(Octal) 


200 
400 
1000 
2000 
4000 


Filename Block Status Word (N.STAT) 


Meaning 

Set if explicit device name string is specified. 

Set if group portion of UIC contains wildcard specification. 
Set if owner portion of UIC contains wildcard specification. 
Set if file name is in ANSI format. 


Set if wildcard character processing is required. 


Tindicates bits that are set if the associated information is supplied through an ASCII data-set descriptor. 


2 Although NB.SD1 and NB.SD2 are defined, they are neither set nor supported by FCS. 


The filename block format for ANSI magnetic tape file names is shown in Figure B-2. 


Figure B-2: ANSI Filename Block Format 
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The filename block offset definitions for ANSI magnetic tape are shown in Table B-3. 
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Table B-3: Filename Block Offset Definitions for ANSI Magnetic Tape 


Symbolic 

Offset Size 

Name (Bytes) Definition 

N.FID 2 File identification field 

N.ANM1 12 First 12 bytes of ANSI filename string 
N.FVER 2 File version number field (binary) 
N.STAT 2 Filename block status word (See bit definitions in Table B-2.) 
N.NEXT 2 Context for next .FIND operation 
N.ANM2 6 Remainder of the ANSI filename string 
N.DVNM 2 ASCII device name field 

N.UNIT 2 Unit number field (binary) 


a 
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Appendix C 
File Header Block 


Table C-1 shows the format of the file header block. The various areas within the file header 
block are described in detail in the following sections. The offset names in the file header block 
may be defined either locally or globally, as shown in the following statements: 


FHDOF$ DEFS$L ;DEFINE OFFSETS LOCALLY. 
FHDOF$ DEF$G ;DEFINE OFFSETS GLOBALLY. 


Table C-1: File Header Block Format 


Size 
Area (Bytes) Content Offset 
Header Area 1 Identification area offset in words H.IDOF 
1 Map area offset in words H.MPOF 
2 File number H.FNUM 
2 File sequence number H.FSEQ 
2 Structure level and system number H.FLEV 
— Offset to file owner information, H.FOWN 
consisting of member number and 
group number 
1 Member number H.PROG 
1 Group number H.PROJ 
2 File protection code H.FPRO 
1 User-controlled file characteristics H.UCHA 
1 System-controlled file characterise H.SCHA 
tics 
3210 User file attributes H.UFAT 
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Table C-1 (Cont.): File Header Block Format 


Size 
Area (Bytes) 


Identification 6 
Area 


PN DN DN NY NY KY 


Map Area 1 
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Content 


Size in bytes of header area of file 
header block 


File name (Radix—50) 


File type (Radix—50) 

File version number (binary) 
Revision number 

Revision date 

Revision time 

Creation date 

Creation time 

Expiration date 

To round up to word boundary 


Size (in bytes) of identification area 
of file header block 


Extension segment number 


Extension relative volume number 
(not implemented) 


Extension file number 
Extension file sequence number 


Size (in bytes) of the block count 
field of a retrieval pointer (1 or 2); 
only 1 is used 


Size (in bytes) of the logical block 
number field of a retrieval pointer 
(2, 3, or 4); only 3 is used 


Words of retrieval pointers in use 
in the map area 


Maximum number of words of 
retrieval pointers available in the 
map area 


Start of retrieval pointers 


Offset 
S.HDHD 


ILFNAM 


I.FTYP 
I.FVER 
IL.RVNO 
IL.RVDT 
ILRVTI 
I.CRDT 
LCRTI 
LEXDT 


S.IDHD 


M.ESQN 
M.ERVN 


M.EFNU 
M.EFSQ 
M.CTSZ 


M.LBSZ 


M.USE 


M.MAX 


M.RTRV 


Table C-1 (Cont.): 


File Header Block Format 


Size 
Area (Bytes) Content Offset 
— Size in bytes of map area of file S.MPHD 
header block 
Checksum 2 Checksum of words 0-255 H.CKSM 
Word 
Note 


The checksum word is the last word of the file header block. Retrieval pointers 
occupy the space from the end of the map area to the checksum word. 


C.1 Header Area 


The information in the header area of the file header block is described in Table C-2. 


Table C-2: File Header Block Contents 


Word Area 


Identification area off- 
set 

Map area offset 

File number 


File sequence number 


Structure level 


File owner information 


File protection code 


Contents 


Word 0, bits 0-7. This byte locates the start of the identification area relative 
to the start of the file header block. This offset contains the number of 
words from the start of the header to the identification area. 


Word 0, bits 8-15. This byte locates the start of the map area relative to 
the start of the file header block. This offset contains the number of words 
from the start of the header area to the map area. 


The file number defines the position this file header block occupies in the 
index file; for example, the index file is number 1, the storage bit map is 
file number 2, and so forth. 


The file number and the file sequence number constitute the file identification 
number used by the system. This number is different each time a header is 
reused. 


This word identifies the system that created the file and indicates the file 
structure. A value of [1,1] is associated with all current Files-11 volumes. 


This word contains the group number and owner number constituting the 
User Identification Code (UIC) for the file. Legal UICs are within the range 
[1,1] to [377,377]. However, UIC [1,1] is reserved for the system. 


This word specifies the manner in which the file can be used and who can 
use it. When creating the file, you specify the extent of protection desired 
for the file. 
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Table C-2 (Cont.): File Header Block Contents 


Word Area 


File characteristics 


User file attributes 


Contents 


This word, consisting of two bytes, defines the status of the file. Following 

is a description of each byte: 

Byte 0 defines the user-controlled characteristics. They are as follows: 

UC.CON = 200 Logically contiguous file. When the file is extended (for 
example, by a WRITE$ or PUT$ macro), bit UC.CON is 
cleared whether or not the extension requests contiguous 
blocks. 


UC.DLK = 100 File improperly closed. 

Byte 1 defines system-controlled characteristics. They are as follows: 
SC.MDL= 200 File marked for deletion. 

SC.BAD=100 Bad data block in file. 


This area consists of 16 words. The first seven words of this area are a 
direct image of the first seven words of the FDB when the file is opened. 
The other nine words of the record I/O control area are not used by FCS, 
although RMS does use them. 


C.2 Identification Area 


Information in the identification area of the file header block is detailed in Table C-3. 


Table C-3: File Header Indentification Area Contents 


Word Area Contents 

File name The file’s creator specifies a file name of up to nine Radix-50 characters 
in length. This name is placed in the name field. The unused portion 
of the field (if any) is zero-filled. 

File type This word contains the file type in Radix-50 format. 


File version number 


Revision number 


Revision date 


Revision time 
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This word contains the file version number, in binary, as specified by 
the creator of the file. 


This word is initialized to 0 when the file is created; it is incremented 
each time a file is closed after being updated or modified. 


Seven bytes are used to maintain the date on which the file was last 
revised. The revision date is kept in ASCII form in the format day, 
month, year (two bytes, three bytes, and two bytes, respectively). This 
date is meaningful only if the revision number is a nonzero value. 


Six bytes are used to record the time at which the file was last revised. 
This information is recorded in ASCII form in the format hour, minute, 
and second (two bytes each). 


Table C-3 (Cont.): File Header Indentification Area Contents 


Word Area 


Creation date 


Contents 


The date on which the file was created is kept in a 7-byte field having 


Creation time 


Expiration date 


the same format as that of the revision date (see above). 


The time of the file’s creation is maintained in a 6-byte field having the 
same format as that of the revision time (see above). 


The date on which the file becomes eligible to be deleted is kept in a 
7-byte field having the same format as that of the revision date (see 


above). Use of expiration is not implemented. 


C.3 Map Area 


The map area contains the information necessary to map virtual block numbers to logical block 
numbers. This is done by means of retrieval pointers, each of which points to an area of 
contiguous blocks. A retrieval pointer consists of a count field and a number field. The count 
field defines the number of blocks contained in the contiguous area pointed to while the logical 
block number (LBN) field defines the block number of the first logical block in the area. 


A value of n in the count field (see Figure C-1) means that n+1 blocks are allocated, starting at 
the specified block number. 


Figure C—1 shows the retrieval pointer format used in the Files-11 file structure. 


Figure C-1: Retrieval Pointer Format 


15 0 
Count Field Number Field 
31 16 
Low LBN 
ZK-303-81 
Note 


The remaining paragraphs in this appendix apply to RSX-11M-PLUS and 
Micro/RSX systems that support the multiheader version of F11ACP. 


The map area normally has space for 102 retrieval pointers. It can map from 102 to 26,112 
blocks. If more retrieval pointers are required, extension headers are allocated to hold additional 
retrieval pointers. Extension headers are allocated within the index file. They are identified by 
a file number and a file sequence as are other file headers; however, extension file headers do 
not appear in any directory. 
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A nonzero value in the extension file number field of the map area indicates that an extension 
header exists. The extension header is identified by the extension file number and the 
extension file sequence number. The extension segment number numbers the headers of 
the file sequentially, starting with a 0 for the initial header. 


Extension headers of a file contain a header area and identification area that are a copy of the 
first header as it appeared when the first extension was created. Extension headers are not 
updated when the first header of the file is modified. 


Extension headers are created and handled by the file control primitives as needed; their use is 
transparent to you. 
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Appendix D 
Statistics Block 


The format of the statistics block is shown in Figure D-1. The statistics block is allocated 
manually in your program as described in Chapter 3. 


Figure D-1: Statistics Block Format 


feo | Shee 
Word 0 (0 If File Is Noncontiguous) 


Lock Count Access Count 
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Appendix E 
Index File Format 


The index file ((0,OJINDEXF.SYS) of a Files-11 volume consists of virtual blocks, starting with 
virtual block 1, the bootstrap block. Virtual block 2 is the home block. Table E-1 describes the 
structure and contents of an index file. 


Table E-1: Index File Structure 
Virtual Block 


Number Index File Element 

1 Bootstrap block 
Home block 

3 Index file bit map (n blocks); the value of n is in the home block 
34+n Index file header 
34n+1 Storage map header 
34n+2 Bad block file header 
34n+3 Master File Directory (MFD) header 
34n+4 Checkpoint file header 
34n+5 User file header 1 
34n+6 User file header 2 


User file header n 
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E.1 Bootstrap Block 


A disk that is structured for Files-11 has a 256-word block, starting at physical block 0. This 
block contains either a bootstrap routine or a message to the operator stating that the volume 
does not contain a bootable system. The bootstrap routine brings a core image into memory 
from a predefined location on the disk. 


E.2 Home Block 


The home block contains volume identification information that is formated as shown in 
Table E-2. This block is located either in logical block 12 or at any even multiple of 256 blocks. 
In addition, you may define offset names in the home block locally or globally by using the 
following commands: 


HMBOF$ DEF$L ;DEFINES OFFSETS LOCALLY. 
HMBOF$ DEF$G ;DEFINES OFFSETS GLOBALLY. 


Table E-2: Home Block Format 


Size 

(Bytes) Content Offset 

2 Index bit map size H.IBSZ 

4 Location of index bit map H.IBLB 

2 Maximum files allowed H.FMAX 

2 Storage bit map cluster factor H.SBCL 

2 Disk device type H.DVTY 

2 Structure level H.VLEV 

1249 Volume name (12 ASCII characters) H.VNAM 

4 Reserved - 

2 Volume owner’s UIC H.VOWN 

2 Volume protection code H.VPRO 

2 Volume characteristics V.VCHA 

2 Default file protection word H.DFPR 

6 Reserved - 

1 Default number of retrieval pointers H.WISZ 
in a window 

1 Default number of blocks to extend H.FIEX 
files 

1 Number of entries in directory least H.LRUC 


recently used (LRU) 
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Table E-2 (Cont.): Home Block Format 


Size 

(Bytes) Content Offset 
110 Available space - 

2 Checksum of words 0-28 H.CHK1 
1419 Creation date and time H.VDAT 


100,;,5 | Volume header label (not used) - 
8210 System-specific information (not used) - 
25419 Relative volume table (not used) - 


210 Checksum of home block H.CHK2 
(words 0-255) 


E.3 Index File Bit Map 


The index file bit map controls the use of file header blocks in the index file. The bit map 
contains a bit for each file header block contained in the index file. The bit for a file header 
block is located by means of the file number of the file with which it is associated. The values 
of the bit map are as follows: 


0 Indicates that the file header block is available. 
The file control primitives can use this block to create a file. 


1 Indicates that the file header block is in use. 
This block has already been used to create a file. 


E.4 Predefined File Header Blocks 


The first five file header blocks of an index file are predefined. Table E-3 describes the contents 
of the predefined blocks. 
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Table E-3: Predefined File Header Blocks 


File Header Block 


Description 


Index File Header 


Storage Map File 
Header 


Bad Block File Header 


Master File Directory 
Header 


Checkpoint File Header 


This is the standard header associated with the index file. 


The storage map is a file that is used to control the assignment of 
disk blocks to files. 


The bad block file is a file that consists of unusable blocks (bad 
sectors) on the disk. 


This header block is associated with the Master File Directory 
(MFD) for the disk. This directory contains entries for the index file, 
the storage map file, the bad block file, the MFD, the checkpoint 
file, and all User File Directories (UFDs). 


This block identifies the file that is used for the checkpoint areas 
for all checkpointable tasks. A task can also have checkpoint space 
in the task image itself. 
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Appendix F 
summary of I/O-Related System Directives 


Table F-1 contains a summary of the I/O-related system directives in alphabetical order. The 
parameters that may be specified with a directive are also described in the order of their 
appearance in the directive. These directives are described in detail in the RSX-11M-PLUS and 
Micro/RSX Executive Reference Manual. 


Table F-1: 


Directive 


ALUN$ 


GLUN$ 


GMCR$ 


Summary of |/O-Related System Directives 


Function and Parameters 


Assign Logical Unit Number 
Assigns a logical unit number (LUN) to a physical device. 
Format 


ALUN$ lun,dev,unt 

lun Specifies the logical unit number (LUN). 

dev Specifies the physical device name (two ASCII characters). 
unt Specifies the physical device unit number. 


Get Logical Unit Number Information 


Fills a 6-word buffer with information about a physical unit to which the LUN is 
assigned. 


Format 


GLUN$ lun, buf 


lun Specifies the logical unit number (LUN). 
buf Specifies the address of a 6-word buffer in which the LUN information is to 
be stored. 


Get MCR Command Line 


Transfers an 80-byte Monitor Console Routine (MCR) command line to the task issuing 
GMCR$. No parameters are required in this directive. 
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Table F-1 (Cont.): Summary of |/O-Related System Directives 


Directive Function and Parameters 


QIO$ Queue I/O Request 
Places an I/O request in the device queue associated with the specified LUN. 


Format 


QIO$ fnc,lun,efn,pri,isb,ast,prl 


fne Specifies the I/O function code. 
lun Specifies the logical unit number (LUN). 
efn Specifies the event flag number. 
pri Specifies the priority of the request (ignored but must be present.) 
isb Specifies the address of the I/O status block (IOSB). 
ast Specifies the entry-point address of the asynchronous system trap (AST) 
service routine. 
prl Specifies the parameter list in the form <P1,...,P6>. 
QIOW$ Queue I/O Request and Wait 


Places an I/O request in the device queue associated with the specified LUN. The 
Executive suspends the task until the specified event flag is set. 


Format 


Qlow$ fnc,lun,efn,pri,isb,ast,pri 


fne 
lun 


efn 


Specifies the I/O function code. 

Specifies the logical unit number (LUN). 

Specifies the event flag number (EFN). 

Specifies the priority of the request (ignored but must be present.) 
Specifies the address of the I/O status block (IOSB). 

Specifies the entry-point address of the AST service routine. 
Specifies the parameter list in the form <P1,...,P6> . 
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Table F-1 (Cont.): Summary of I/O-Related System Directives 


Directive 
RCST$ 


RCVD$ 


RCVX$ 


SDAT$ 


Function and Parameters 


Receive Data or Stop 


Instructs the system to dequeue a 13-word data block for the task issuing RCST$; the 
data block was queued for the task with a Send Data directive (SDAT$) or a Send, 
Request, and Connect directive (SDRC$). 


Format 
RCST$ tname, buf 


tname Specifies the name of the sending task (if not specified, data may be received 
from any task.) 


buf Specifies the address of a 15-word buffer to receive the sender task name 
and data. 
Receive Data 


Receives a 13-word data block that has been queued (FIFO) by a Send Data directive 
(see SDAT$ and SDRC$, which follow). 


Format 
RCVD$ tsk, buf 
tsk Specifies the name of the sending task. 


buf Specifies the address of the 15-word data buffer (2-word sending task name 
and 13-word data block.) 
Receive Data or Exit 


Receives a 13-word data block if queued by a Send Data directive (see SDAT$ and 
SDRC$ following), or the task exits if no data is queued. 


Format 


RCVX$ tsk, buf 


tsk Specifies the name of the sending task (if not specified, data may be received 
from any task.) 

buf Specifies the address of the 15-word data buffer (2-word sending task name 
and 13-word data block.) 

Send Data 


Queues (FIFO) a 13-word block of data for a task to receive and declares a significant 
event. 


Format 

SDAT$ tsk, buf,efn 

tsk Specifies the name of the receiving task. 

buf Specifies the address of the 13-word data buffer. 
efn Specifies the event flag number (EFN). 
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Table F-1 (Cont.): Summary of I/O-Related System Directives 
Directive Function and Parameters 


SDRC$ Send, Request, and Connect 


Executes a Send Data directive to the specified task, requests the Executive to activate 
the task if it is not already active, and then connects to the task. 


Format 

SDRC$ tname,buf,efn, east 

tname Specifies the target task name of the offspring task to be connected. 
buf Specifies the address of a 13-word send buffer. 


efn Specifies the the event flag to be cleared on issuance and set when the 
offspring task exits or emits status. 


east Specifies the address of an AST routine to be called when the offspring task 
exits or emits status. 
SDRP$ Send Data Request and Pass Offspring Control Block 


Sends a data packet for the specified task, chains to the requested task, and requests 
the task if it is not already active. 


Format 


SDRP$ task, bufadr, buflen,efn,flag 


task Specifies the name of the task to be chained to. 

bufadr Specifies the address of the buffer to be given to the requested task. 
buflen Specifies the length of the buffer to be given to the requested task. 
efn Specifies the event flag. 

flag Specifies the flags byte controlling the execution of this directive. The 


flag bits are defined as follows: 


SD.REX = 128; Force this task to exit upon successful completion of 
this directive. 


SD.RAL = 119 Pass all connections to the requested task (default is 
pass none). If you specify this flag, do not specify 
the parent task name. 


Note 
The target task may not be a 
CLI task. 


SD.RNX = 21 Pass the first connection in the queue, if there is 
one, to the requested task. If you specify this flag, 
do not specify the parent task name. 
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Table F-1 (Cont.): Summary of |/O-Related System Directives 


Directive 
SMSG$ 


VRCD$ 


VRCS$ 


Function and Parameters 


Send Message 


Creates and sends a formatted data packet to a system-defined target task. The only 
valid target for the Send Message directive is the Error Logger. The task that issues 
the SMSG$ directive must be privileged. 


Format 


SMSG$ tgt,buf,len,<pri,..., prn> 


tgt Specifies the target identifier. 
buf Specifies the address of optional data buffer. 
len Specifies the length, in bytes, of optional data buffer. 


<pri,...pm> Specifies the target-specified parameter list. 


Variable Receive Data 


Instructs the system to dequeue a variable length data block for the task issuing 
VRCD$. The block was queued by the Variable Send Data directive. If you specify 
the sending task, only data sent by that task is received. 


Format 

VRCD$ task, bufadr,buflen 

task Specifies the sender task name. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer size in words (256,, words maximum). The default is 
1319 words. The first two words are the sender task name. The data block 
follows. 

Variable Receive Data or Stop 


Instructs the system to dequeue a variable-length data block for the task issuing VRCS$. 
The block was queued by a Variable Send Data directive. If there is no packet, the task 
issuing VRCS$ is stopped. The sending task is expected to issue an Unstop directive 
after sending the data. When you specify a sender task, only data sent by that task is 
received, 


Format 

vRCS$ task, bufadr , buflen 

task Specifies the sender task name. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer size in words (256,;) words maximum). The default is 
13,9 words. The first two words are the sender task name. The data block 
follows. 
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Table F-1 (Cont.): Summary of |/O-Related System Directives 


Directive 
VRCX$ 


VSDA$ 


Function and Parameters 


Variable Receive Data or Exit 


Instructs the system to dequeue a variable-length data block for the issuing task. The 
data block was queued for the task by a Variable Send Data directive. If you specify 
a sender task, only data sent by that task is received. If no data has been sent to the 
task issuing VRCX$, the task exits. 


Format 

VRCX$ task, bufadr, buflen 

task Specifies the name of the sending task. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer length (a maximum of 256;) words). The default is a 
minimum of 13;) words. The first two words are the sender task name. 


Variable Send Data 


Instructs the system to queue a variable-length data block for the specified task to 
receive. If you specify an event flag, a significant event is declared when the directive 
executes successfully. 


Format 

VSDA$ task, bufadr,buflen 

task Specifies the receiving task name. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer size in words (a maximum of 256) words). The default 
is 13,9) words. 
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Table F-1 (Cont.): 


Directive 


summary of I/O-Related System Directives 


Function and Parameters 


VSRC$ 


Variable Send, Request, and Connect 


Performs a Variable Send Data to the specified task, requests the task if it is not already 
active, and then connects to the task. 


Format 


VSRC$ tname, buf, buflen,efn, east, esb 


tname 
buf 
buflen 


efn 


east 


esb 


Specifies the target task name of the offspring task to be connected. 
Specifies the address of send buffer. 


Specifies the length of the buffer (a maximum of 256;) words). The default 
is 1349 words, 


Indicates the event flag cleared when the directive was issued and set when 
the offspring task exited or emitted status. 


Specifies the address of an AST routine to be called when the offspring task 
exits or emits status. 


Specifies the address of an 8-word status block to be written when the 
offspring task exits or emits status. The following list contains a description 
of the status words: 


Word 0 Offspring task exit status 
Word 1 Task Termination and Notification (TKTN) program abort code 
Words 2-7 _ Reserved 
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Appendix G 
Support of ANSI Magnetic Tape Standard 


This appendix defines the American National Standards Institute (ANSI) magnetic tape labeling 
standard, which is a level three implementation of the ANSI standard, Magnetic Tape Labels 
and File Structure for Information Interchange (X3.27-1978). The exceptions are that ANSI does 
not support spanned records and that DIGITAL’s tape system does not support user-supplied 
labels. User-supplied labels may appear on a tape; however, they are accessible to application 
programs only through the unlabeled tape feature. 


G.1 Volume and File Labels 
Tables G-1, G-2, G-3, and G-4 present the format of volume labels and file header labels. 


G.1.1 Volume Label Format 
Table G-1 describes the volume label format for ANSI magnetic tape. 


Table G-1: Volume Label Format 


Character Length 

Position Field Name (Bytes) Contents 

1-3 Label identifier 3 VOL 

4 Label number 1 1 

5-10 Volume identifier 6 Contains the volume label and any ANSI “a” charac- 


ter. An “a” character is defined by the ANSI standard 
as any of the uppercase letters A-Z, the digits 0-9, 
and the following special characters: 


space! "%&' ()*+,- ./: 3; <=> 7) 
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Table G-1 (Cont.): Volume Label Format 


alent A etl ie 


Character 
Position 


11 


Field Name 
Accessibility 


Reserved 


Owner 
identification 


Reserved 


Label standard 
version 


Length 
(Bytes) 


1 


Contents 


Contains any ANSI “a” character. A space indicates 
no restriction. You can specify the “a” character 
with the /VOLUME_ACCESSIBILITY:“c” qualifier 
in the DCL command INITIALIZE. Any ANSI “a” 
character is allowed. The default character is a space. 
Refer to the RSX-11M-PLUS MCR Operations Manual 
or RSX-11M-PLUS Command Language Manual for 
more information on INITIALIZE. Micro/RSX system 
users may also refer to the Micro/RSX User's Guide, 
Volume 1. 


Spaces 


The contents of this field are system dependent 
and are used for volume protection purposes. See 
Section G.1.1.1. 


Spaces 
3 


ee ee a 8 8S SOO 


G.1.1.1 Contents of Owner Identification Field 


The owner identification field is divided into the following three subfields and a single pad 
character: 


1. System identification (positions 38 to 40) 


2. Volume protection code (positions 41 to 44) 
3. User Identification Code (UIC) (positions 45 to 50) 


4. A numeric 1 (position 51) 


The system identification consists of the following character sequence: 


Dix 


The machine code is indicated by x, which can be one of the following: 


8—PDP-8 
A—DECsystem-10 
B—PDP-11 
F—PDP-15 


The D%x characters provide an identification method so that the remaining data in the owner 
identification field can be interpreted. The /OWNER switch to the MCR command INI allows 
you to overwrite these characters. The / OWNER=“owner” qualifier to the DCL command 
INITIALIZE allows you to overwrite these characters. (Refer to the RSX-11M-PLUS MCR 
Operations Manual and the RSX-11M-PLUS Command Language Manual for more information. 
Micro/RSX system users may also refer to the Micro/RSX User’s Guide, Volume 1.) In the case of 
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tapes produced on PDP-11 systems, the default system identification is D%B and the volume 
protection code and UIC are interpreted as described in the list that follows. 


The volume protection code in positions 41 to 44 defines access protection for the volume 
for four classes of users. Each class of user has access privileges specified in one of the four 
columns, as follows: 

a es 


Position Class 
ee 


41 System (UIC no greater than [7,255]j9) 

42 Owner (group and member numbers match) 
43 Group (group number matches) 

44 World (any user not in one of the above) 


I ee Se 
One of the following access codes can be specified for each character position: 


ee ee ee 
Code Privilege 
ee 


0 No access 

1 Read access only 

2 Extend (append) access 
3 Read/extend access 

4 Total access 


—_—_eeeeee Se eee 


The UIC is specified in character positions 45 to 50. The first three characters are the group 
code in decimal. The next three are the user code in decimal. 


The last character in the owner identification field is a numeric 1. 
The following is an example of the owner identification field: 
Owner identifier - D%B14100631461 

1. The file was created on a PDP-11. 


2. System and group have read access. 
Owner has total access. 
All others are denied access. 


3. The UIC is [063,146]. 


G.1.2 User Volume Labels 


User volume labels are never written or passed back to you. If present, they are skipped. 
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G.1.3 File Header Labels 


You should consider the following information before creating file header labels: 


e The Files-11 naming convention uses a subset (Radix-50) of the available ANSI character 
set for file identifiers. 


¢ One character in the file identifier, the period (.), is fixed by Files-11. 


¢ A maximum of 13 of the 17 bytes in the file identifier are processed by Files-11. 


e It is strongly recommended that all file identifiers be limited to the Radix-50 PDP-11 
character set, and that no character other than the period (.) be used in the file type 
delimiter position for data interchange between PDP-11 and DECsystem-10 systems. 


¢ For data interchange between DIGITAL and non-DIGITAL systems, the preceding conven- 
tions should be followed. If they are not, refer to Section G.1.3.1. 


Tables G-2, G-3, and G-4 describe the HDR1, HDR2, and HDR3 labels, respectively. 


Table G-2: 


Character 
Position 


1-3 


55-60 
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File Header Label (HDR1) 


Field Name 
Label identifier 
Label number 
File identifier 
File set 
identifier 

File section 
number 


File sequence 
number 


Generation number 
Generation version 


Creation date 


Expiration date 
Accessibility 


Block count 


Length 
(Bytes) 


3 
1 
17 


Contents 

HDR 

1 

Contains any ANSI “a” character. See Table G-1. 


Contains the volume identifier of the first volume in 
the set of volumes. 


Contains numeric characters. This field starts at 0001 
and is increased by 1 for each additional volume used 
by the file. 


Contains the file number within the volume set for 
this file. This number starts at 0001. 


Contains numeric characters. 
Contains numeric characters. 
_yyddd (_ indicates space) 
00000 if no date 

Same format as creation date. 
Space’ 

000000 


Table G-2 (Cont.): 


File Header Label (HDR1) 


Contents 


-— eee 


Contains the three letters DEC, followed by the 
name of the system that produced the volume. See 
Section G.1.1.1. 


Examples: DECFILE11A DECSYSTEM10 
Pad name with spaces. 


Spaces 


-_ OO eee 


Character Length 
Position Field Name (Bytes) 
61-73 System code 13 
74-80 Reserved 7 
Table G-3: File Header Label (HDR2) 
Character Length 
Position Field Name (Bytes) 
1-3 Label identifier 3 

4 Label number 1 

5 Record format 1 

6-10 Block length 5 
11-15 Record length 5 
16-50 System-dependent 35 

information 

51-52 Buffer offset 2 
53-80 Reserved 28 


Contents 
HDR 
2 


F indicates fixed length. 

D indicates variable length. 
S indicates spanned. 

U indicates undefined. 


Contains numeric characters. 
Contains numeric characters. 


Positions 16 to 36 are spaces, 


Position 37 defines carriage control and can contain 
one of the following: 


A Indicates first byte of record contains 


FORTRAN control characters. 


space Indicates line feed /carriage return is to be 
inserted between records. 


M Indicates the record contains all form control 
information. 


If DEC appears in positions 61 to 63 of HDR1, 
position 37 must be as previously specified. 


Positions 38 to 50 contain spaces. 


Contains numeric characters; 00 on tapes produced 
by Files-11. Supported only on input to Files-11. 


Spaces 


To 
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Table G-4: File Header Label (HDR3) 


ee ee ee 


Character Length 
Position Field Name (Bytes) 
1-3 Label identifier 3 

4 Label number 1 

5-68 System-dependent 64 
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Contents 
HDR 
3 


Contains file attributes specified at creation time. 
Each of the 32 bytes of user file attributes is expanded 
into two hexadecimal characters. The first seven 
words of this area are a direct image of the first seven 
words of the File Descriptor Block (FDB) when the 
file is opened. These are the same words in the file- 
attribute section of the FDB given in Appendix A. The 
other nine words are not used by File Control Services 
(FCS) though they are used by Record Management 
Services (RMS). 


The following list translates the user file attribute 
bytes to the corresponding hexadecimal character 
pair: 


Byte Pair Byte Pair 


1 4 17 20 
2 3 18 19 
3 2 19 18 
4 1 20 17 
5 8 21 24 
6 7 22 23 
7 6 23 22 
8 5 24 21 
9 12 25 28 
10 11 26 27 
11 10 27 26 
12 9 28 25 
13 16 29 32 
14 15 30 31 
15 14 31 30 
16 13 32 29 


Table G-4 (Cont.): File Header Label (HDR3) 
Character Length 


Position 


69-80 


Field Name (Bytes) Contents 


Using the list, the eighth hexadecimal character pair 
is the expansion of the fifth user file attribute byte, 
and the fourth user file attribute byte is expanded into 
the first hexadecimal character pair. The hexadecimal 
pair is the normal representation of the contents of 
the byte; that is, if the byte contains a 1549, the 
hexadecimal representation of it is OF. 


Reserved 10 Spaces 


G.1.3.1 File Identifier Processing by Files—11 


The magnetic tape Ancilliary Control Processor (ACP) processes Files—11 type file identifiers. 
However, if the file name is enclosed in quotes, it is processed as an ANSI file name, all “a’ 
characters are legal, all 17 positions may be used, and the only conversion that takes place is 
making all lowercase characters into uppercase characters and converting all characters that are 
not “a” characters to question marks. 


At file input, the file identifier is handled as follows: 


1. 


The first nine characters at a maximum are processed by an ASCII-to-Radix-50 converter. 
The conversion continues until one of the following occurs: 


a. A conversion failure occurs. 
b. Nine characters are converted. 
c. A period (.) is encountered. 


If the period is encountered, the next three characters after the period are converted and 
treated as the file type. If a failure occurs or all nine characters are converted, the next 
character is examined for a period. If it is a period, it is skipped and the next three characters 
are converted and treated as the file type. 


The version number is derived from the generation number and the generation version 
number is as follows: 


(generation number - 1)*100 + generation version + 1 


If an invalid version number is computed, it will be changed to 1. 


At file output, the file identifier is handled as follows: 


1. 


The file name is placed in the first positions in the file identifier field. It can occupy up to 
nine positions and is followed by a period. 


The file type of up to three characters is placed after the period. The remaining positions 
are padded with spaces. 


The version number is then placed in the generation and generation version number fields, 
as described in the following formulas: 


a. Generation number = (°7S0"—1)4 1 
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b. Generation version # = version# —1Modulo 100 
(Note that, in both calculations, remainders are ignored.) 


The following are examples of Files-11 versions and their generation version numbers. 


Files-11 Generation 
Version No. Generation No. Version No. 
1 1 0 

50 1 49 

100 1 99 

101 2 

1010 11 


G.1.4 End-of-Volume Labels 
End-of-volume labels are identical to the file header labels, with the following exceptions: 
* Character positions 1 to 3 contain EOV instead of HDR. 


® The block count field contains the number of records in the last file section on the volume. 


G.1.5 File Trailer Labels 


End-of-file labels (file trailer labels) are identical with file header labels, with the following 
exceptions: 


¢ Columns 1 to 3 contain EOF instead of HDR. 


e The block count contains the number of data blocks in the file. 


G.1.6 User File Labels 


User file labels are never written or passed back to you. If present, they are skipped. 


G.2 File Structures 


The file structures illustrated below are the types of file and volume combinations that the file 
processor produces. The file processor can read and process additional sequences. 


The minimum block size and fixed-length record size is 18 bytes. The maximum block size is 
8192 bytes. FCS adapts to input files of varying block size. 


If HDR2 is not present, the data type is assumed to be fixed (F), and the block size and record 
size are assumed to be the default value for the file processor. The default for both block 
and record size is 512j) bytes. You can override these block and record sizes with the MAG 
command (see Section G.5), and the MOUNT command. The MAG command controls biock 
and record size on unlabeled tapes and on ANSI level 1 and 2 tapes. 
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The meaning of the symbols used in the file structure illustrations is as follows: 


1. The asterisk (*) indicates a tape mark. As defined by ANSI, a tape mark is a special control 
block recorded on magnetic tape to serve as a separator between files and file labels. 


BOT indicates beginning of tape. 
EOT indicates end of tape. 


The comma (,) indicates the physical record delimiter. 


G.2.1 File Structure Format 


Table G-—5 lists the various file structures and their format. 


Table G-5: File Structures 


File/Volume 

Combinations Structure Format 

Single File BOT, VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1,EOF2,EOF3** 
Single Volume 

Single File BOT,VOL1,HDR1,HDR2,HDR3+*—DATA—*EOV1,EOV2,EOV3+* 
Multivolume BOT, VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1,EOF2,EOF3** 

Mulltifile BOT, VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1,EOF2,EOF3*HDR1, 
Single Volume HDR2,HDR3*—DATA—*EOF1,EOF2,EOF3** 

Multifile BOT,VOL1,HDR1,HDR2,HDR3*-DATA-—*EOF1,EOF2,EOF3*HDR1,HDR2, 


Multivolume HDR3*-DATA-*EOV1,EOV2,EOV3+* 
BOT, VOL1,HDR1,HDR2,HDR3*-DATA-*EOF1,EOF2,EOF3*HDR1,HDR2, 
HDR3*-DATA-* EOF1,EOF2,EOF3** 


G.3 End-of-Tape Handling 


End-of-tape is handled by the magnetic tape file processor. Files are continued on the next 
volume provided that the volume is already mounted or mounted upon request. A request for 
the next volume is printed on CO (console output pseudo device). 


G.4 ANSI Magnetic Tape File Header Block (FCS Compatible) 


Figure G-1 illustrates the format of a file header block that is returned by the file header 
READ ATTRIBUTE command for ANSI magnetic tape. The header block is constructed by the 
magnetic tape primitive from data within the tape labels. 


G.5 The Magnetic Tape Control Task 


The Magnetic Tape Control Task (MAG) allows you to specify file attributes for unlabeled tapes, 
provides positioning functions for both unlabeled and ANSI tapes, and allows you to respond 
to requests for new tapes or volumes without mounting a new tape. 


This command can only be used on mounted tapes. The keywords are valid for both unlabeled 
and ANSI tapes, unless otherwise noted. 
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Figure G-1: ANSI Magnetic Tape File Header Block (FCS Compatible) 


H.FLEV 


Structure Level = 401, 
UIC (For Volume) 


H.FOWN=H.PROG 
Header Area 


Protection Code (For Volume) H.FPRO 
Record Attributes Record Type Code H.UFAT 
Record Size in Bytes 
n Words of Zeros 
X+.FNAM 


(IDENT Offset *2)=x 


File Name RAD50 


File Type RAD50 LFTYP 
File Version Number XH.FVER 
Zeros (Revision Date and Time) X+1.RVNO 
Creation Date and Time (000000) X+H.CRDT 
Identification 
Area Expiration Date X+H.EXDT 
Pad Byte of Zero X+4710 
Copy of the Ri 
HDR1 Label 
Copy of the HDR2 Label 
(If byte 1 of label = 0, X+13010 
label is not present.) 
Map Area Null Map, That Is, Zeros X+21019 = 


(10 Bytes Long) (Map of Offset 2) 


ZK-3 15-81 
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Format 
> MAG SET mmnn:/keyword[/keyword|s}] 


Parameter 


mmnn: 
Specifies the magnetic tape unit on which the operation is to be performed. 


Keywords 
/BS=number-of-bytes 
NONE 
/CC=type of carriage control | LIST 
FORTRAN 
/EOF 
/EOT 
/EOV 


/INITIALIZE=“volume id” 
/POS=number-of-files 
/RS=number-of-characters 
/REWIND 


Keyword Descriptions 


/BS=number-of-bytes 
Specifies the number of characters (bytes) per block on a mounted tape. You can specify 
the number of characters in either decimal or octal. To specify a decimal number, terminate 
it with a period. The default is octal. 


This block size becomes the default for the tape. FCS uses this value on output when 
there is no HDR2 label present on an ANSI magnetic tape, and when no other value was 
specified on creation of the file. FCS reads the file attributes to obtain the block size when 
opening an existing file on ANSI magnetic tape. 


The value specified for block size must be greater than 1419 bytes. There is no maximum 
block size. FCS pads a block on ANSI magnetic tape to an even length to permit PUT$ 
operations with odd fixed-length records. 


/CC=type of carriage control 
Specifies the type of carriage control. The default is /CC=NONE. 
Valid types of carriage control are as follows: 


NONE 
LIST 
FORTRAN 


When reading from an ANSI tape, FCS uses these carriage controls if one of the following 
occurs: 


¢ No HDR2 label is present. 
¢ The HDR2 label contains a system identification other than DEC or OS. 
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If an HDR2 label is present, FCS uses the information in the HDR2 label and ignores the 
/CC keyword. 


This keyword is the only way to specify carriage control for unlabeled tapes. 


/EOF 
Causes the ACP to return the I/O status code IE.EOF to the requesting task. You can use 
this keyword to terminate a request for another tape in a volume set. 


This keyword is only valid for ANSI tapes. 


/EOT 
Causes the ACP to return the I/O status code IE.EOT to the requesting task. You can use 
this keyword to terminate a request for another tape in a volume set. 


This keyword is only valid for ANSI tapes. 


/EOV 
Causes the ACP to return the I/O status code JE.EOV to the requesting task. You can use 
this keyword to terminate a request for another tape in a volume set. 


This keyword is only valid for ANSI tapes. 


/INITIALIZE="Volume id” 

Specifies the volume label to which the tape will be initialized. This keyword allows 
you to create a new volume to satisfy a request from the ACP for a new output volume 
for an ANSI tape. The format of the volume identifier is identical to the format of the 
volume identifier specified for the MOUNT command. Refer to the INITIALIZE command 
in the RSX-11M-PLUS Command Language Manual or the RSX-11M-PLUS MCR Operations 
Manual for details. Micro/RSX system users may also refer to the Micro/RSX User's Guide, 
Volume 1. 


This keyword is only valid for ANSI tapes. 

/POS=number-of-files 
Specifies the number of files (tape marks) to be spaced over from the current tape position. 
For example, /POS=0 means access the current file; /POS=1 means space forward one file 


from the current position. The number of files may be specified in either decimal or octal. 
To specify a decimal number, terminate the number with a period. The default is octal. 


The number of files specified must be between 0 and 23,4173. 


This keyword is only valid for mounted unlabeled tapes. This keyword is not necessary for 
labeled tapes because files can be accessed by name. 


If a tape containing ANSI or IBM’ labels is mounted as unlabeled, the formula to calculate 
the position of a data file is: 


N= (N-1)*3+1 
N is the number of the desired file. 


1 IBM is a registered trademark of the International Business Machines Corporation. 
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/RS=number-of-characters 
Specifies the number of characters of each record for fixed-length records on tape. 


Maximum record size is the block size. 


When reading files from an ANSI tape, FCS uses this value for record size when no HDR2 
label is present. 


This keyword is the only way to specify record size for unlabeled tapes. 


/REWIND 
Specifies that the tape is to be rewound to BOT. For ANSI tapes, this keyword rewinds to 
the beginning of the volume set. 


G.5.1 MAG Command Example 
The following example displays the use of the MAG command. 


>MOU MMO: /NOLABEL/TR=EBCDIC 
>MAG SET MMO: /BS=80. /RS=80. /CC=LIST/REWIND 


>! Read the first "file" on the tape to determine the actual tape format 


>PIP TI:=MMO:X 

VOLiX234870 NASHUA 

HDR1DEC2. KP72132 X2348700010001 80256 802860000000IBM OS/VS 370 
HDR2F008000008030DEC2K009/DEC2U009 B 60337 


>! This information shows that the tape in fact has labels that 

>! resemble ANSI labels (this tape is in the format of 

>! another computer manufacturer). The actual block size and record size 
>! can be determined from the labels. 

>! Use the MAG SET command to set the actual block and record size. 


>MAG SET MMO: /BS=800./RS=80. 


>! Use the MAG SET /POS command to position to the next file on the tape. 
>! You could also position to the file by specifying 

>! a position to PIP as follows: PIP TI:=MMO:"POS=Ri" 

>! where R indicates REWIND and 1 is the number of tape 

>! marks to space over. 


>MAG SET MMO: /REWIND/POS=1 


>! Read the data file. Note that PIP requires a dummy file name, even 
>! though the tape is already positioned at the correct file. 


>PIP TI:=MMO:X 


001 321 03054 MERRIMACK 603 
002 456 03060 NASHUA 603 
003 789 03051 HUDSON 603 
004 124 01845 NORTH ANDOVER 617 
005 345 64801 JOPLIN 714 


Support of ANSI Magnetic Tape Standard G-13 


G.5.2 MAG Command Error Messages 
MAG - Device not mounted or mounted foreign 


Explanation: The specified device must be either a mounted ANSI tape or a mounted 
unlabeled tape. A foreign tape that is mounted foreign is not known to the magnetic tape 
ACP and is therefore the same as an unmounted tape. The MAG command only supports 
mounted tapes. 


User Action: Mount the device with the /NOLABEL qualifier if it is an unlabeled tape. Do 
not use the MAG command with tapes that are mounted foreign. 


MAG - Get command line failure 


Explanation: An illegal indirect command file name was specified or MAG could not find 
the specified indirect command file. 


User Action: Check the specification for the indirect command file and reenter the command 
line. 


MAG - Illegal combination of keywords 


Explanation: Keywords were specified that required both an unlabeled tape and an ANSI 
tape. 


User Action: Refer to the keyword descriptions in this chapter to determine which switches 
require ANSI tapes and which require unlabeled tapes. 


MAG - Illegal file attributes combination 
Explanation: A record size was specified that was not less than or equal to the block size. 


User Action: Specify a record size less than or equal to the block size. 


MAG -- Illegal switch value 
Explanation: This message indicates one of the following: 
e /POS value was greater than 9999. 
e /BS value was less than 14. 
e —/RS value was less than 14. 


User Action: Determine which value was illegal and retype the command line. 


MAG - Invalid device or unit 
Explanation: The specified device does not exist or is not a magnetic tape. 


User Action: Determine the correct device or unit and retype the command line. 


MAG - Operation is only valid for mounted ANSI tapes 


Explanation: An operation that is only valid for ANSI magnetic tape was attempted on an 
unlabeled tape. 


User Action: Use only valid commands. 


G-14 Support of ANSI Magnetic Tape Standard 


MAG - Operation is only valid for unlabeled tapes 


Explanation: An operation that is only valid for unlabeled tapes was attempted on an ANSI 
tape. 


User Action: Use only valid commands. 


MAG - Privilege violation 


Explanation: On systems with multiuser protection, only the terminal to which the tape 
drive is allocated may change the tape characteristics. 


User Action: Reenter the command from the terminal that owns the tape drive. 


MAG - Requested operation inconsistent with tape state 
Explanation: This message is returned when either of the following occurs: 
¢ The user specified /EOF, /EOV, or /EOT and the magnetic tape ACP rejected it. 
¢ The user specified /INITIALIZE and the ACP rejected it. 


User Action: Determine the state of the tape and type only commands that can be performed 
in the current state. 


MAG - Syntax error 
Explanation: The command was specified incorrectly. 


User Action: Check the correct syntax as described in this chapter; then, reenter the command 
line. 


G.6 Unlabeled Tape 


A tape that contains no labeling information is called an unlabeled tape. An unlabeled tape 
contains either blocked or unblocked fixed-length records. When a tape is mounted with the 
/NOLABEL qualifier on the MOUNT (MCR command MOU) command, FCS and RMS can 
access records on the tape by using standard read and write operations. This is different from 
mounting a tape foreign (DCL command MOUNT/FOREIGN or MCR command MOU /FOR). 
When a tape is mounted foreign, records on the tape must be accessed directly by using the 
QIO$ operations that are defined for the magnetic tape driver. 


G.6.1 Block Size on Tapes Mounted /NOLABEL 


Under certain conditions, if a file is written to a tape, its block size will be even and one more 
than the value specified in the MOUNT command. The conditions where this occurs are as 
follows: 


¢ The tape is mounted /NOLABEL. 
¢ The mount command specifies an odd record size. 


¢ The mount command specifies an odd block size. 
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FCS adds the padding character, a 136, circumflex (*), to odd-sized byte blocks because of a 
hardware restriction; some tape drives will not allow an odd number of bytes to be transferred 
to or from tape. Therefore, blocks of data are padded with the circumflex character so that even 
blocks of data can be written to tape on any tape drive. 


G.6.2 Tape Positioning 


Any tape motion before the first read operation must be explicitly requested in one of the 
following ways: 


The FA.ENB!IFA.RWD bit may be set in F.ACTL to request a rewind of the volume set prior 
to create or find-file operations. 


The MAG SET /POS command may be specified to space forward a specified number of 
files from 0 to 9999. 


The MAG SET /REWIND command may be specified to rewind the tape to BOT. 


The file may be referenced by the name “POS=[R][nnnn]”, where R indicates that the tape is 
to be rewound, and nnnn is the number of files (tape marks) to space forward. For example, 
to read the second file on a tape use the following: 


>PIP TI:=MM:"POS=0001" 


Each tape mark delimits a file. All positioning operations are in terms of tape marks. If any 
type of label is present on the tape, it will be treated as a file. 


When a file is deaccessed, position within the file is always consistent. 


G.6.3 Specifying File Attributes 


You can specify the attributes for files to be read from tape in three ways: 


1. 


Use the MOUNT command. (See the RSX-11M-PLUS MCR Operations Manual or the 
RSX-11M-PLUS Command Language Manual. Micro/RSX system users may also refer to the 
Micro/RSX User's Guide, Volume 1.) 


Issue any create operation request. You can issue the create request from within your 
program by creating a file and by closing the file without writing any data, or by using the 
RMS DEFINE utility. The FCS Create routine returns the error code IE.BTP (bad record 
type) if an attempt is made to set the record type to anything other than fixed length. 


Use the MAG SET command (see Section G.5). 
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G.6.4 Tape Translation 


You can request translation for a tape when you mount it with the MCR command MOU 
or the DCL command MOUNT. (See the RSX-11M-PLUS MCR Operations Manual or the 
RSX-11M-PLUS Command Language Manual. Micro/RSX system users may also refer to the 
Micro/RSX User's Guide, Volume 1.) If you have requested translation, your data buffer (the FCS 
or RMS block buffer) is translated within your task. Therefore, on a write operation, the data 
in your task is destroyed. 


You can add up to three installation-dependent translation routines to the magnetic tape ACP 
by adding routines with the following format: 


USERn:: MOV #TBLPTR,RO sn is i, 2, or 3. 
RETURN 

TBLPTR: .WORD INTRAN 
.WORD OUTRAN 


INTRAN: <A 256 byte table for input translation> 
OUTRAN: <A 256 byte table for output translation> 


An example of the EBCDIC translation tables that are provided with your system is shown in 
Section G.6.5. 


You must include these translation routines in the Overlay Description Language (ODL) for the 
magnetic tape ACP when the MTAACP task is built. Comments within the files MTABLD.ODL 
and MTABLD.CMD indicate where these routines may be added. 


G.6.5 Example of EBCDIC Translation Tables 


Following is an example of the EBCDIC translation tables that are provided with your system. 


EBCDIC: : MOV #TBLPTR , RO 
RETURN 


TBLPTR: .WORD EBCASC 
-WORD ASCEBC 


.NLIST BEX 
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EBCASC: .BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
.BYTE 


ASCEBC: .BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
.BYTE 
.BYTE 
. BYTE 
.BYTE 
. BYTE 


000 ,001 ,002,003,040,011,040,177 ,040,040 
040 ,013,014,015,016, 017,020,021 ,022,023 
040 040,010,040, 030,031, 040,040 ,040 ,035 
040 ,037 ,040, 040,034,040, 040,012,027 ,033 
040 ,040,040 040,040,005 , 006,007 ,040 ,040 
026 040,040, 036,040,004, 040,040 ,040 ,040 
024 ,025 ,040,032, 040,040, 040,040,040 ,040 
040 ,040 040,040, 133, 056 , 074,050,053, 135 
046 ,040,040, 040,040,040, 040,040 ,040 ,040 
041 ,044,052,051,073, 136,055 , 057 ,040 ,040 
040 ,040,040, 040,040,040, 174,054,045, 137 
076 ,077 , 137 ,040,040, 040, 040,040 ,040 ,040 
040, 140,072,043, 100,047,075 042,040,141 
142,143,144,145,146, 147,150,151 ,040,040 
040,040,040, 040,040,152,153,154, 155,156 
157 , 160,161, 162,040,040, 040,040 ,040,040 
040,176,163, 164,165,166, 167,170,171,172 
040 ,040,040, 040,040,040, 040,040,040 ,040 
040 ,040,040,040, 040,040, 040,040 ,040 ,040 
040 ,040,173,101,102, 103,104,105, 106,107 
110,111,040,040,040,040,040,040,175,112 
113,114,115,116,117,120,121,122,040,040 
040 040,040,040, 134,040,123, 124,125,126 
127,130,131, 132,040,040, 040,040,040 ,040 
060 , 061 , 062 , 063 ,064, 065 , 066 , 067 ,070 ,071 
040 ,040 ,040 ,040 ,040,040 


000 , 001 , 002,003 , 067 , 055 , 056 , 057 
026,005 ,045 013,014,015, 016,017 
020 ,021,022,023,074,075 ,062,046 
030,031,077 ,047 ,042,035 , 065 , 037 
100, 132,177,173,133, 154,120,175 
115,135,134,116,153,140,113,141 
360 , 361, 362, 363 , 364, 365 , 366, 367 
370 ,371,172,136,114,176,156,157 
174,301,302, 303 , 304,305 , 306, 307 
310, 311,321, 322,323,324 ,325, 326 
327 ,330, 331,342,343, 344,345,346 
347 ,350,351,112,340,117 ,137, 155 
171,201, 202, 203 , 204, 205 , 206 , 207 
210,211, 221,222,223 , 224 , 225,226 
227 , 230, 231,242,243 , 244,245,246 
247 , 250,251,300, 152,320, 241,007 
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; 50. 


; 100. 


; 150. 


; 200. 


; 250. 


BYTE 000,001,002 ,003 , 067 ,055 , 056 ,057 
BYTE 026,005 ,045,013,014,015, 016,017 
.BYTE 020,021,022 ,023 ,074,075 , 062 , 046 
-BYTE 030,031,077 , 047 ,042,035 , 065 , 037 
BYTE 100,132,177,173,133,154,120,175 
BYTE 115,135,134,116,153,140, 113,141 
-BYTE 360,361,362 ,363 , 364, 365 , 366, 367 
-BYTE 370,371,172,136,114,176, 156,157 
BYTE 174,301,302,303,304, 305,306,307 
-BYTE 310,311,321, 322,323,324, 325, 326 
-BYTE 327,330,331 ,342,343,344,345,346 
BYTE 347,350,351, 112,340,117 ,137,155 
-BYTE 171,201,202, 203,204, 205 , 206,207 
BYTE 210,211,221, 222,223,224, 225,226 
-BYTE 227,230,231, 242,243, 244,245, 246 
BYTE 247,250,251, 300,152,320, 241,007 


-ENABLE QUIET 
.ENABLE SUBSTITUTION 


.; This command file is invoked with the command 


ne QMTA outspec=Mx:infile 


.; and searches a tape mounted unlabeled (which has an ANSI-like structure) 
.; for the file "infile" and copies it to outspec. 


.; Parse the command line; OUTSPC gets outspec, 


a DEV gets Mx, 


a INFILE gets the file name to find on tape. 


.PARSE COMMAN " " OUTSPC COMMAN 

.PARSE COMMAN "=" QUTSPC INSPEC 

.PARSE INSPEC ":" DEV INFILE 

.IF INFILE EQ "" .GOTO NOTMT 

.SETS INFILE INFILE+" " 
.SETS INFILE INFILE[1:17.] 

.SETS JUNK DEV[1:1] 

.IF JUNK NE "M" .GOTO NOTMT 


.; Make a name for the temp file. 
.TESTFILE TI: 


.PARSE <FILSPC> ":" TMP JUNK 
.SETS TMP TMP+".TMP" 


.; Always start at the beginning of the tape. 


MAG SET 'DEV': /REWIND 


.; Labels have a block and record size of 80. 


MAG SET 'DEV':/BS:80./RS:80. 
- LOOK: 
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; 300 


G.7 Example Using an Indirect Command File to Read a Tape 


The following example shows how to read a tape by using an indirect command file: 


G-19 


.; Put the labels in a temp file so Indirect can look at then 


PIP 'TMP'='DEV’ : DUMMY. NAM 
.OPENR 'TMP! 

.READLB: 

.READ LABEL 

.IFT <EOF> .GOTO NOSUCH 
.SETS LABELT LABEL[1:3] 


.; Skip any Volume header labels 


.IF LABELT = "VOL" .GOTO READLB 
.IF LABELT NE "HDR" .GOTO ILLFMT 
.SETS LABELT LABEL[4:4] 

.IF LABELT NE "1" .GOTO ILLFMT 
.SETS LABELT LABEL[5:21.] 


.; If the names do not match, go get the next set of labels. 


.IF LABELT NE INFILE .GOTO TRYNXT 


.; We have found the file, see if there is a HDR2 with size info. 


-READ LABEL 

.IFT <EOF> .GOTO READFL 

.SETS LABELT LABEL[1:4] 

.IF LABELT NE "HDR2" .GOTO READFL 


.; Yes, we have a HDR2 label. 


.SETS LABELT LABEL([37. :37.] 
.SETS CC "LI" 

.IF LABELT = "A" .SETS CC "FO" 
.IF LABELT = "M" .SETS CC "NO" 
.SETS BS LABEL[6:10.] 

.SETS RS LABEL[11.:15.] 


.; Set up the block size, record size, and carriage control 
.; based on what was in HDR2. 


MAG SET 'DEV':/BS:'BS'./RS:'RS'./CC:'CC' 
.SETS LABELT LABEL[5:5] 

.IF LABELT EQ "F" .GOTO READFL 

.DISABLE QUIET 


!'MTA - Warning, Record Format is 'LABELT'; only F Format is fully supported. 


-ENABLE QUIET 
-READFL: 
. CLOSE 


.; Transfer the file. 
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PIP 'QUTSPC'='DEV' :"POS=1" 
-GOTO ENDIT 

- TRYNXT: 

. CLOSE 

MAG SET 'DEV': /POS=3 

-GOTO LOOK 

. ILLFMT: 

-DISABLE QUIET 

.DISABLE MCR 


MTA - Tape is not in a format that I understand. 


.GOTO ENDIT 
.NOTMT: 
-DISABLE QUIET 
-DISABLE MCR 


MTA - Input file spec must specify a magnetic tape device and a file name. 


. EXIT 

. NOSUCH: 
.-DISABLE QUIET 
.DISABLE MCR 


MTA - No such file -- 'INSPEC' 


-ENDIT: 

-ENABLE MCR 
-ENABLE QUIET 

PIP 'TMP';_/DE/NM 
- EXIT 
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Appendix H 
QIOS Interface to the ACPs 


This appendix describes the QIO$ level interface to the file Ancillary Control Processors (ACPs). 
These include F11ACP for Files—11 disks and MTAACP for American National Standards 
Institute (ANSI) magnetic tape. Because ACPs work in direct relation with the Executive, they 
are very effective and are able to perform operations that device drivers cannot. In addition, all 
RSX-11M-PLUS and Micro/RSX directives can be issued by ACPs. 


F11ACP supports the following QIO functions: 


Function Code Meaning 


10.CRE Create file 

IO.DEL Delete file 

1O.ACR Access file for read only 
IO.ACW Access file for read/write 
IO.ACE Access file for read/write/extend 
IO.DAC Deaccess file 

1O.EXT Extend file 

IO.RAT Read file attributes 

1O.WAT Write file attributes 

IO.FNA Find file name in directory 
IO.RNA Remove file name from directory 
IO.ENA Enter file name in directory 
IO.ULK Unlock block 
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MTAACP supports the following QIO functions: 


Function Code Meaning 


IO.FNA Find file by name 

IO.ENA Enter name in directory (nonoperational) 
10.ACR Access for read only 
10.ACW Access for read/write 
10.ACE Access for read/write /extend 
I0.DAC Deaccess file 

IO.RVB Read virtual block 

IO.WVB Write virtual block 

IO.EXT Extend file 

10.CRE Create file 

IO.RAT Read attributes 

IO.APC ACP control 

IO.APV Privileged ACP control 


H.1 How to Use the ACP QIO$ Functions 


Although the operations described in this appendix are normally performed by the file-access 
methods Record Management Services (RMS) and File Control Services (FCS), your application 
may issue the ACP QIO$s. Using ACPs allows you the opportunity to speed up processing 
time with device I/O because ACPs already contain device-specific structure. 


The required parameters for each QIO$ are described in the preceding section. The necessary 
steps for common operations are described in the following section. 


Note 
The file identifier is the only way to refer to a file. 
H.1.1 Creating a File 
To create a file, perform the following tasks: 
1. Use IO.CRE to create the file. 


2. Enter the file in the Master File Directory (MFD) or a User File Directory (UFD) with 
IO.ENA. 
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H.1.2 Opening a File 


To open a file, perform the following tasks: 


1. Use IO.FNA to find the file identifier of the directory in the MFD. 
2. Use IO.FNA to find the file identifier of the file in the directory. 
3. Access the file with IO.ACR, IO.ACW, or IO.ACE. 


H.1.3 Closing a File 
To close a file, deaccess the file with IO.DAC. 


H.1.4 Extending a File 
To extend a file, perform the following tasks: 
1. Use IO.FNA to find the file identifier if the file is not accessed. 
2. Use IO.EXT to extend the file. 


H.1.5 Deleting a File 


To delete a file, perform the following tasks: 
1. Use IO.FNA to find the file identifier. 


2. Use IO.RNA to remove the directory name. 
3. Use IO.DEL to delete the file. 


H.2 Errors Returned by the File Processors 
The error codes returned by F11ACP and MTAACP are shown in Table H-1. 


Table H-1: File Processor Error Codes 
Error 

Code Operations 

IE.ABO IO.RVB/IO.WVB 

IE.ALC Extend or create operation 


IE.ALN 


IE.BAD 


An attempt to access a file 


Any function 


Explanation 


Indicates that not all requested data was transferred 
by the device. 


Indicates that the operation failed to allocate the 
file because of placement control or because of 
other related problems. 


Indicates that a file is already accessed on that 
logical unit number (LUN). 


Indicates that a required parameter is missing, that 
a parameter that should not be present is present, 
that a parameter that must be disabled is enabled, 
or that a parameter value is invalid. 
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Table H-1 (Cont.): 


Error 
Code 


Operations 


File Processor Error Codes 


Explanation 


IE.BDR 


IE.BHD 


IE.BVR 


IE.BYT 


IE.BTP 


TE.CKS 


IE.CLO 


TE.DFU 


TE.DUP 
TE.EOF 


TE.HFU 


IE. IFC 
TE.IFU 


Directory operations 


Any operation 


Directory operations 


Any function 


Unlabeled Magtape Create 


Any operation 
File access operations 
An allocation request 


An enter name operation 


1O.RVB/IO.WVB/IO.DEL 


An extended operation 


Returned by exec 


Create or extend operation 
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Indicates that you attempted a directory operation 
on a file that is not a directory, or that the specified 
directory is corrupted. This is usually caused by a 
0 version number field. 


Indicates that a corrupt file header was encoun- 
tered, or that the operation required a feature not 
supported by the file control processor (FCP) (such 
as multiheader support or support for unimple- 
mented features). 


Indicates that you attempted to enter a name in a 
directory with a negative or 0 version number. 


This error is returned if the buffer specified is on 
an odd-byte boundary or is not a multiple of 4 
bytes. 


Indicates an attempt was made to create an 
unlabeled tape file with a record type other than 
fixed. 


Indicates that the checksum of a file header is 
incorrect. 


Indicates that the file was locked against access by 
the “deaccess lock bit.” 


Indicates that there is insufficient free disk space 
for the requested allocation. 


Indicates that the name and version already exist. 


On read operations, this indicates an attempt to 
read beyond end-of-file. On truncate operations, it 
indicates an attempt to truncate a file to a length 
longer than that allocated or that the file was 
already at EOF. 


Indicates that the file header is full and cannot 
contain any more retrieval pointers and that adding 
an extension header is not allowed. When this 
error code is returned on a create operation, it 
indicates that the index file could not be extended 
to allow a file header to be allocated. 


Indicates illegal function code. 


Indicates that there are no file headers available 
based on the parameters specified when the vol- 
ume was initialized. 
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Error 
Code 


TE.LCK 


TE.LUN 


IE.NOD 


IE.NSF 


IE.OFL 
IE.PRI 


IE.RER 


IE.SSNC 


IE.SPC 
IE.SQC 


TE.WAC 


TE.WAT 


Operations 

Returned on file access, direc- 
tory operations, and on truncate 
Any operation requiring a file 
ID 


All file operations that require 
pool 


All file operations 


Returned by exec 


Any operation 


Any operation 


Any operation 


Returned by exec 


Any operation 


File access operations 


Write attributes and deaccess 


Explanation 


Indicates that the file is already accessed by a writer 
and that shared write has not been requested or is 
not allowed. 


Indicates that file ID has not been supplied and 
that the file is not accessed on the LUN. 


Indicates that an I/O request failed because of 
IE.UPN, and that the FCP was unable to allocate 
required space from DSR or from secondary pool 
for data structures. 


Indicates that the specified directory entry does not 
exist, that a file corresponding to the file ID does 
not exist, or that the file is marked for deletion. 


Indicates that the device is off line. 


Indicates that the user does not have the required 
privilege for the requested operation, or that the 
user has not requested the proper access to the file 
if the file is already accessed (for example, in an 
attempt to write to a file that is accessed for read). 
This error code also indicates an attempt to do file 
I/O to a device that is not mounted. 


Indicates that the FCP encountered a fatal device 
read error during an operation; the operation has 
been aborted. 


Indicates that the file number and the value 
contained in the header do not agree. This 
generally means that the header has gone bad 
because of a crash or a hardware error. 


Indicates an illegal buffer. 


Indicates that the file sequence number does not 
agree with the file header; usually indicates that 
the file has been deleted and the header has been 
reused. 


Indicates that the file is already write accessed and 
that lock against writers is requested. 


Indicates that the FCP encountered an invalid 
attribute. 
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Table H-1 (Cont.): File Processor Error Codes 


Error 
Code Operations Explanation 
IE.WER Any operation Indicates that the FCP encountered a fatal device 


write error during an operation. The operation 
has been aborted, but the disk structure may have 
been corrupted. 


IE.WLK Any operation requiring write Indicates that the volume is software write-locked. 
access 


H.3 QIOS Parameter List Format 


The device-independent part of a file processing QIO$ parameter list is identical to all other 
QIO$ lists. The general QIO parameter list is described in detail in the RSX-11M-PLUS and 
Micro/RSX I/O Drivers Reference Manual. The file processor QIO$s require the following six 
additional words in the parameter lists: 


Parameter word 1 Specifies the address of a 3-word block containing the file identifier. 
Parameter word 2 Specifies the address of the attribute list. 
Parameter words 3 Specifies the size and extend control information. 
and 4 
Parameter word 5 Specifies the window size information and access control. 
Parameter word 6 Specifies the address of the filename block. 

Note 


The Micro/RSX Executive treats file identifier blocks, filename blocks, and 
attribute list entries as read/write data. For this reason, they may not be used 
in read-only code segments or libraries. 


H.3.1 File Identification Block 


The File Identification Block is a 3-word block containing the file number and the file sequence 
number. The format of the File Identification Block is shown in Figure H-1. 


Figure H~1: File Identification Block 


File Number 


File Sequence Number 


Reserved 


2K-4095-85 
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F11ACP uses the file number as an index to the file header in the index file. Each time a header 
block is used for a new file, the file sequence number is incremented. This ensures that the file 
header is always unique. The third word is not currently used but is reserved for the future. 


H.3.2 The Attribute List 


The file attribute list controls F11ACP reads or writes. File attributes are fields in the file header. 
These fields are described in detail in Chapter 2. 


The attribute list contains a variable number of entries terminated by an all-0 byte. The 
maximum number of entries in the attribute list is six. 


An entry in the attribute list has the following format: 


.BYTE <Attribute type>, Attribute size 
-WORD Pointer to the attribute buffer 


H.3.2.1 The Attribute Type 


This field identifies the individual attribute to be read or written. The sign of the attribute type 
code determines whether the transfer is a read or write operation. If the type code is negative, 
the ACP reads the attribute into the buffer. If the type code is positive, the ACP writes the 
attribute to the file header. Note that the sign of the type code must agree with the direction 
implied by the operation. For example, if the type code is positive, the operation must be an 
IO.WAT or IO.DAC function code. 


The attribute type is one of the following: 
e = File owner (H.FOWN) 


The file owner User Identification Code (UIC) is a binary word. The low byte is the owner 
number and the high byte is the group number. 


¢ File protection (H.FPRO) 
The file protection word is a bit mask with the following format: 
Each of the fields contains four bits, as follows: 
Bit 1 Read access 
Bit 2 Write access 
Bit 3 Extend access 
Bit 4 Delete access 
e File characteristics (H.UCHA) 
The following user characteristics are currently contained in the 1-byte H.UCHA field: 
UC.CON = 200 Logically contiguous file 
UC.DLK = 100 File improperly closed 
* Record I/O Area (U.UFAT) 


This field contains a copy of the first seven words of the File Descriptor Block (FDB). 
(RMS uses 32 bytes. The first seven are compatible with FCS for sequential files.) See 
Appendix A for a description of the FDB. 
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e File name (I.FNAM) 


The file name is stored as nine Radix—50 characters. The fourth word of this block contains 
the file type and the fifth word contains the version number. 


e File type (I.FTYP) 
The file type is stored as three Radix-50 characters. 
e Version number (I.FVER) 
The version number is stored as a binary number. 
¢ Expiration date (I-EXDT), creation date (I.CRDT), revision date (I.RVDT) 


The expiration date is currently unused. When the file is created, the ACP initializes the 
creation date to the current date and time. It initializes the expiration and revision dates 
to 0. The ACP sets the revision date to the current date and time each time the file is 
deaccessed by a write access routine. 


e Statistics block 

This block is described in Appendix D. 
e Read entire file header 

This buffer is assumed to be 10003 bytes long. You cannot write this attribute. 
¢ Revision number (IL.LRVNO) 


The ACP sets the revision number to 0, and the ACP increments it every time the file is 
deaccessed by a write access routine. 


e Placement control 


Placement control is described in Section H.4. 


H.3.2.2 Attribute Size 


This byte specifies the number of bytes of the attribute to be transferred. Legal values are from 
1 to the maximum size of the particular attribute. Table H-2 shows the maximum size for each 
attribute type. 


Table H-2: Maximum Size for Each File Attribute 


Maximum 

Attribute Attribute Type 
Type Code Attribute Type (Octal Bytes) 

1 File owner 6 

2 Protection 4 

3 File characteristics 2 

4 Record I/O area 40 

5 File name, type, and version number 12 
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Table H-2 (Cont.): Maximum Size for Each File Attribute 


Maximum 
Attribute Attribute Type 
Type Code Attribute Type (Octal Bytes) 
6 File type 4 
7 Version number 2 
10 Expiration date 7 
11 Statistics block 12 
12 Entire file header 0 
13 Block size (magnetic tape only) — 
15 Revision number and creation/revision/expiration 43 
dates 
16 Placement control 16 


H.3.2.3 Attribute Buffer Address 


The attribute buffer address field contains the address of the buffer in the user’s task space to 
or from which the attribute is to be transferred. 


H.3.3 Size and Extend Control 


The size and extend control parameters specify how many blocks the file processor allocates to 
a new file or adds to an existing file. These parameters also control the type of block allocation. 


The format is as follows: 


-BYTE <High 8 bits of size>, <extend control> 
-WORD <Low 16 bits of size> 


The size field specifies the number of blocks to be allocated to a file on IO.CRE and IO.EXT 
operations, and the field specifies the final file size on IO.DEL operations. 


The extend control field controls the manner in which an extend operation is to be executed. 
The following bits are defined: 

Bit Definition 

EX.AC1=1 The extend size is to be added as a contiguous block. 

EX.AC2=2 Extend by the largest available contiguous piece up to the specified size. 
EX.FCO=4 The file must end up contiguous. 


EX.ADF~10 Use the default rather than the specified size. The default extend size is the 
size that was specified when the volume was mounted. 
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Bit Definition 


ON Sinn Eee oe ee ee ee 


EX.ALL=20 Placement control (see Section H.4). 
EX.ENA=200 Enable extend. 


BNE en ee a ee 


H.3.4 Window Size and Access Control 


The window and access control parameter specifies the window size and access control 
information in the following format: 


.BYTE <window size>, <access control> 
This word is only processed if the high bit of the access control byte (AC.ENB) is set. 


Window size is the number of mapping entries. Specifying a negative window size minimizes 
window turns. If this byte is zero, the file processor uses the volume default. The size of the 
window allocated in the pool is 6 times the number of mapping entries (each mapping entry is 
3 words), plus 10 bytes for the window control block. 


On Micro/RSX systems with secondary pool support, the mapping entries are allocated in 
secondary pool. The window control block and a pointer to secondary pool are located in 
primary pool. 


The following access control bits are defined: 


cS a ee 


Bit Definition 
AC.LCK=1 Lock out further accesses for Write or Extend 


AC.DLK=2 Enable deaccess lock 


The deaccess lock sets the lock bit in the file header if the file is deaccessed as 
the result of a task exit without explicitly deaccessing the file. The lock bit is 
set by the Executive. The lock bit is not set when the system crashes. 


AC.LKL=4 Enable block locking 

AC.EXL=10 Enable explicit block unlocking 

AC.ENB=200 Enable access 

AC.RWD=10 Rewind the volume (labeled and unlabeled magnetic tape only) 
AC.UPD=100 Update mode (labeled magnetic tape only) 

AC.POS=20 _Do not position to end-of-volume (labeled magnetic tape only) 
AC.WCK=40 __ Initiate driver write-checking 


Note 


Both AC.LKL and AC.EXL must be set if you want block 
locking. If you do not want block locking, both bits must 
be clear. Any other combination is an error. 
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H.3.5 Filename Block Pointer 


The filename block pointer contains the address of a 15-word block in the issuing task’s space. 
This block is called the filename block. The filename block is described in detail in Appendix B. 


The fields of the filename block that are particularly important in file-processing operations are 
as follows: 


¢ Directory identification (N.DID) 


This field is required for all disk operations. It specifies the directory to which the operation 
applies. This field is not used for tape operations. 


e File identification (N.FID) 


This field is required as input for enter operations. This field is returned as output by find 
and remove operations. 


e File name (N.FNAM), file type (N.FTYP), and file version number (N.FVER) 


These fields are required as input to enter, find, and remove operations. For find and remove 
operations, the file processor locates the appropriate entry by matching the information in 
these fields with the directory entries. 


e Status word (N.STAT) 
° Wildcard context (N.NEXT) 


This field is required as input for wildcard operations. It specifies the point at which to 
resume processing. It is updated for the next operation. It must initially be set to 0. 


H.4 Placement Control 


The placement control attribute list entry controls the placement of a file in a particular place 
on the disk. You can specify either exact or approximate placement on IO.CRE and IO.EXT 
operations. 


The placement control entry must be the first entry in the attribute list. 
The format of the placement control attribute list entry is as follows: 


.BYTE placement control,0 

.WORD high-order bits of VBN or LBN 

.WORK low-order bits of VBN or LBN 

-BLKW 4 ;Buffer to receive starting and ending LBN if AL.LBN is set. 


The following bits are defined for the placement control field: 


Bit Definition 


OT 


AL.VBN=1 Set if block specified is a virtual block number (VBN); otherwise, the block is 
the logical block number (LBN). 


AL.APX=2 Set if you want approximate placement; otherwise, placement is exact. 


AL.LBN=4 Set if you want starting and ending LBN information. 
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H.5 Block Locking 


Block locking only occurs when the user accesses a file with AC.LKL and AC.EXL set in the 
access control byte of the parameter list. Any read or write operation causes a check to see if 
the block is locked. 


A write access locks a block for exclusive access. A write operation can only access a block that 
is not locked by any accessor. The only exception to this is an exact match with a previous 
lock owned by the same accessor. 


A read access locks a block for shared access. A read operation can access any block locked for 
shared access. 


The user must unlock a block with the explicit unlock request, IO.ULK. You may use IO.ULK 
to unlock one or all locked blocks. 


If all accessors to a file have not requested block locking, the F11ACP returns an error (see 
Table H-1). 


When the file is deaccessed, all locks owned by the accessor are released. 


Each active lock requires 8 bytes from the system primary pool storage region. This storage is 
deallocated when the file is deaccessed. 


H.6 Summary of F11ACP Functions 


The following is a summary of the functions implemented in F11ACP. A list of accepted 
parameters follows each function. All parameters are required unless specified as optional. 
Parameters other than those listed are illegal for that function and must be 0. 


Function Parameter Meaning 
a SSSSSSeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeSSS 
IO.CRE Create file 


#1 Indicates the file identifier block is filled in with the file identifier 
and sequence number of the created file. 


#2 Indicates write attribute and/or placement control list (optional). 
#3 & #4 Indicates extend control (optional). 


The amount allocated to the file is returned in the high byte of 
IOST(1) plus IOST(2). 


#5 May be nonzero but must be disabled. 
10.DEL Delete or truncate file 
#1 Optional if the file is accessed. 
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mn 


Function 


Parameter 
#3 & #4 


Meaning 


Scat trae SS i Ee ee ee 
Indicates size to truncate the file to. If not enabled, the file is 


10.ACR 
10.ACW 
I0.ACE 


10.DAC 


1O.EXT 


1O.RAT 


I0.FNA 
10.RNA 
10.ENA 


10.ULK 


#1 
#2 
#5 


#1 
#2 
#5 


#1 
#2 
#3 & #4 


#1 
#2 


#5 
#6 


#2 
#4 & #5 


deleted. If enabled, the remaining 31 bits specify the size the file is 
to be after truncation. The change in file allocation is returned in 
the high byte of IOST(1) plus IOST(2). This amount will be zero or 
negative. 


Access file for read only 

Access file for read/write 

Access file for read/write/extend 
Indicates file identifier pointer. 

Indicates read attributes control (optional). 
Indicates access control must be enabled. 
Deaccess file 

Indicates file identifier pointer (optional). 
Indicates write attributes control list. 

May be nonzero but must be disabled. 
Extend file 

Optional if file is accessed. 

Indicates placement control attribute list (optional). 
Indicates extend control. 


The amount allocated to the file is returned in the high byte of 
IOST(1) plus IOST(2). 


Read attributes 

Optional if file is accessed. 

Indicates read attributes control list. 
Find name in directory 

Remove name from directory 

Enter name in directory 

May be nonzero but must be disabled. 
Indicates filename block pointer. 
Unlock block 

Indicates 0 or count of blocks to unlock. 


Indicates starting virtual block number (VBN) to unlock or 0 to 
unlock all blocks. 
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Function Parameter Meaning 
10.RVB Read virtual block 
10.WVB Write virtual block 
#1 Indicates user buffer. 
#2 Indicates buffer length. 
#4 & #5 Indicates virtual block number (VBN). 


H.7 Summary of MTAACP Functions 


The following is a summary of the functions implemented in MTAACP. A list of accepted 
parameters follows each function. All parameters are required unless specified as optional. 
Parameters other than those listed are illegal for that function and must be 0. 


Function 


I0.FNA 


IO.ENA 
10.ACR 


10.ACW 


10.ACE 


Parameter 


#5 


#6 


#1 


#2 
#5 


#1 


#2 


Meaning 
Find file by name 


Indicates that the volume is to be rewound prior to the search when 
AC.RWD is set in the access control byte. 


Indicates pointer to filename block. 


The following fields are used as input: N.FNAM, N.FTYP, N.FVER, 
and N.STAT. 


The following fields are returned by MTAACP: N.FID, N.FNAM, 
N.FTYP, N.FVER, and N.STAT. 


Enter name in directory— nonoperational for magnetic tape 
Access for read only 


Indicates file identifier pointer. Used to position a tape by file 
identifier. 


Indicates read attribute list (optional). 
Ignored. 
Access for read/write 


This function will be rejected with the error code IE.PRI. (Extend 
access is required.) 


Access for read/write /extend 


Indicates file identifier pointer. Used to position tape by file 
identifier. 


Indicates read attribute list (optional). 
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Function 


Parameter 
#5 


Meaning 


Indicates AC.UPD (update mode). If AC.UPD is set, the tape will 


I0.DAC 


IO.RVB 


IO.CRE 


#1 
#5 


#1 
#2 


#4 
#5 


#1 


#2 


#5 


#6 


be positioned to overwrite the file and all files beyond the current 
file will be lost. If AC.UPD is not set, the tape will be positioned 
for append. If the file is not the last files MTAACP returns the error 
code IE.ISQ. 


Deaccess file 
Indicates file identifier pointer is ignored. 


Indicates that the volume is to be rewound after the file is closed 
when AC.RWD is set. 


Read virtual block 
Indicates buffer address. 


Indicates buffer size. The buffer size must be greater than 18 bytes 
and less than the declared block length for the entire file. 


Indicates a high virtual block number (VBN). 
Indicates a low VBN. 


Note 


The virtual block number must be either zero 
or exactly 1 greater than the previous block 
number. 


Create File 


Indicates the file identifier pointer. The file sequence and section 
number will be returned to the user’s file identifier block. 


Indicates attribute list pointer. Used to write the attributes for the 
newly created file. Attribute type code must be positive. 


If AC.RWD is set, the volume will be positioned at the beginning 
and will overwrite the first file. This effectively reinitializes the 
volume. 


If AC.RWD is not set and AC.POS is set, the volume set will be 
positioned to the next file position beyond the current file and will 
overwrite that file. All files beyond that on the volume will be 
destroyed. 


If neither AC.RWD nor AC.POS is set, the volume set will be 
positioned at its end and the new file will be appended to the set. 


For unlabeled tapes, MTAACP only checks AC.RWD. 


Filename block pointer. 
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Function Parameter Meaning 
10.RAT Read Attributes 
#1 Indicates the file identifier pointer. Used to position the tape by the 
file identifier. 
#2 Indicates attribute list pointer (see Section H.1.2). 
The following attribute list entries are meaningful for magnetic tape: 

1,2 VIC 

1,4 UIC and protection 

1,5 UIC, protection, and characteristics 

22 Protection 

2,3 Protection and characteristics 

3,1 Characteristics 

4,32 User file attributes 

5,6 File name 

5,8 File name and type 

5,10 File name and type 

6,2 File type 

6,4 File type and version number 

7,2 Version number 

8,7 Expiration date 

-9,10 Statistics block (read only) 

-10,0 Entire header (read only) 

11,2 Block size 

IO.APC ACP Control 
#3 Indicates one of the following user control function codes: 

1 Rewind volume set. 

2 Position to end of volume set. 

3. Close current volume and continue processing the next 
section of the same file on the next volume of the volume 
set. 

4 Space physical records in currently accessed file. 

5 Get ACP characteristics. 

6 Rewind current file. 

10.APV Privileged ACP Control 


This function is used only by the MOUNT and DISMOUNT 
commands. This interface is subject to change and, therefore, will 
not be documented until a future release. 
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Appendix | 
Field Size Symbols 


1.1 System Library Symbols 


Table I-1 describes the field size symbols that reside in the System Library (SYSLIB). These 
symbols are global symbols that are resolved at task-build time through SYSLIB. 


Table I-1: Field Size Symbols 
Symbol Description 


S.BFHD Indicates the size of the file storage region (FSR) block buffer header in bytes. 
S.FATT Indicates the size of the File Descriptor Block (FDB) file attribute area in bytes. 
F.FDB Indicates the size of the FDB in bytes (including the name block). 

F.FNAM Indicates the size of the file name in bytes (stored in Radix—50 format). 

S.FNB Indicates the size of the filename block (FNB) in bytes. 

S.FNBW Indicates the size of the filename block in words. 


S.FNTY Indicates the size of the file name and file type in words (stored in Radix-50 
format). 


S.FSR2 Indicates the size of the FSR2 (basic impure area). 
S.FTYP Indicates the size of the file type in bytes (stored in Radix-50 format). 


F.NFEN Indicates the size of a complete file name in bytes—file ID, name, type, and 
version. 
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Appendix J 
Sample Programs 


The sample programs that follow read records from an input device, strip off any blanks to the 
right of the data portion of the record, and write the data record on an output device. While the 
programs are intended primarily for card reader input and printer output, device independence 
is maintained. 


J.1 Program CRCOPY 


The following example is the main program and is entitled CRCOPY. Sections J.2 and J.3 contain 
programs that are variations of CRCOPY (CRCOPA and CRCOPB). 


.TITLE CRCOPY ;Card reader copy routine 


.MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A , NMBLK$ , FSRSZ$ 
.MCALL OPEN$R,OPEN$W,GET$, PUT$ ,CLOSE$ , EXIT$S 
-MCALL FINIT$ 


INLUN=3 ;Assign CR or file device 
OUTLUN=4 ;Assign to output device 
FSRSZ$ 2 

FDBOUT: FDBDF$ ;Allocate space for output FDB 
FDAT$A R.VAR,FD.CR ;Init file attributes 
FDRC$A_ ,RECBUF,80. ;Init record attributes 
FDOP$A OUTLUN, ,OFNAM ;Init file open section 

FDBIN: FDBDF$ ;Allocate space for input FDB 
FDRC$A_ , RECBUF ,80. ;Init record attributes 
FDOP$A INLUN, , IFNAM ;Init file open section 

RECBUF: .BLKB 80. ;Record buffer 

OFNAM: NMBLK$ OUTPUT,DAT ;Output filename 

IFNAM: NMBLK$ INPUT,DAT ;Input filename 

START: FINIT$ ;Init file storage region 
OPEN$R #FDBIN ;Open the input file 
BCS ERROR ;Branch if error 
OPEN$W #FDBOUT ;Open the output file 
BCS ERROR ;Branch if error 

GTREC: GET$ #FDBIN ;Note - URBD is all set up 
BCS CKEOF ;Error should be EOF indication 
MOV F.NRBD(RO) ,R1 ;Ri=size of record read 
MOV #RECBUF , R2 
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ADD R1,R2 ;R2=address of last byte+1 
10$: CMPB #40, -(R2) ;Strip trailing blanks 

BNE PTREC 

SOB R1,10$ 


:At this point, R1 contains the stripped size of the 
;record to be written. If the card is blank, 
;a zero-length record is written. 


PTREC: PUT$ #FDBOUT, ,R1 :Ri is needed to specify 
BCC GTREC ;the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSE$ RO ;Close the input file 
BCS ERROR 
CLOSE$ #FDBOUT ;Close the output file 
BCS ERROR 
EXIT$S ;Issue exit directive 
. END START 


J.2 Program CRCOPA 


The following sample program is entitled, CRCOPA. The CRCOPA program uses a data-set 
descriptor instead of the default filename block used in CRCOPY. 


.TITLE CRCOPA ;Card reader copy routine 


-MCALL FDBDF$,FDAT$A,FDRC$A, FDOP$A , NMBLK$ , FSRSZ$ 
-MCALL OPEN$R, OPEN$W,GET$ , PUT$ , CLOSE$ ,EXIT$S 
-MCALL FINIT$ 


INLUN=3 ;Assign CR or file device 
OUTLUN=4 ;Assign to output device 
FSRSZ$ 2 


FDBOUT: FDBDF$ 
FDAT$A R.VAR,FD.CR 
FDRC$A_ ,RECBUF,80. 
FDOP$A OUTLUN, OFDSPT 
FDBIN: FDBDF$ 
FDRC$A_ , RECBUF ,80. 
FDOP$A INLUN,IFDSPT 
RECBUF: .BLKB 80. 


CFDSPT: .WORD 0,0 ;Device descriptor 
-WORD 0,0 ;Directory descriptor 
-WORD ONAM$Z,ONAM ;Filename descriptor 

IFDSPT: .WORD 0,0 :Device descriptor 
-WORD 0,0 ;Directory descriptor 
.WORD INAMSZ,INAM ;Filename descriptor 


ONAM: -ASCII /QUTPUT.DAT/ 
ONAMSZ=. -ONAM 


. EVEN 
INAM: -ASCII /INPUT.DAT/ 
INAMSZ=. - INAM 
. EVEN 
START: FINIT$ ;Init file storage region 
OPEN$R #FDBIN ;Open the input file 
BCS ERROR iBranch if error 
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OPEN$W #FDBOUT ;Open the output file 


BCS ERROR ;Branch if error 
GTREC: GET$ #FDBIN ;Note - URBD is all set up 
BCS CKEOF ;Error should be EOF indication 
MOV F .NRBD(RO) ,R1 ;R1i=size of record read 
MOV #RECBUF , R2 
ADD R1,R2 ;R2=address of last bytet+i 
10$: CMPB #40, - (R2) ;Strip trailing blanks 


BNE PTREC 
SOB R1,10$ 


;At this point, R1 contains the stripped size of the 
;record to be written. If the card is blank, 
;a zero-length record is written. 


PTREC: PUT$ #FDBOUT, ,R1 ;R1 is needed to specify 
BCC GTREC ;the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSE$ RO ;Close the input file 
BCS ERROR 
CLOSE$ #FDBOUT ;Close the output file 
BCS ERROR 
EXIT$s ;Issue exit directive 
.END START 


J.3 Program CRCOPB 


The following program is entitled CRCOPB. The CRCOPB program uses run-time initialization 


of the File Descriptor Block (FDB). 
-TITLE CRCOPB :Card reader copy routine 


-MCALL FDBDF$,FDAT$A,FDRC$A, FDOP$A , NMBLK$ , FSRSZ$ 
.MCALL OPEN$R,OPEN$W,GET$ ,PUT$ ,CLOSE$ , EXIT$S 
-MCALL FINIT$,FDAT$R 


INLUN=3 ;Assign CR or file device 
OUTLUN=4 ;Assign to output device 
FSRSZ$ 2 


FDBOUT: FDBDF$ 
FDBIN: FDBDF$ 
RECBUF: .BLKB 80. 


CFDSPT: .WORD 0,0 ;Device descriptor 
-WORD 0,0 ;Directory descriptor 
-WORD ONAM$Z,ONAM ;Filename descriptor 

IFDSPT: .WORD 0,0 ;Device descriptor 
-WORD 0,0 ;Directory descriptor 
-WORD INAMSZ,INAM ;Filename descriptor 


ONAM: -ASCII /OUTPUT.DAT/ 
ONAMSZ=.-ONAM 
.EVEN 
INAM:  .ASCII /INPUT.DAT/ 
INAMSZ=. -INAM 
. EVEN 
START: FINIT$ :Init file storage region 
OPEN$R #FDBIN,#INLUN,#IFDSPT, , #RECBUF , #80. 
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;Runtime initialization 


BCS ERROR ;Branch if error 
FDAT$R #FDBOUT,#R. VAR, #FD.CR ;Runtime initialization 
OPEN$W RO,#OUTLUN,#0FDSPT, , #RECBUF , #80. 
BCS ERROR ;Branch if error 
GTREC: GET$ #FDBIN ;Note - URBD is all set up 
BCS CKEOF ;Error should be EOF indication 
MOV F .NRBD(RO) ,R1 ;Ri=size of record read 
MOV #RECBUF ,R2 
ADD R1,R2 :R2=address of last byte+1 
10$: CMPB #40, - (R2) ;Strip trailing blanks 
BNE PTREC 
SOB R1,10$ 


;At this point, Ri contains the stripped size of the 
:record to be written. If the card is blank, 
:a zero-length record is written. 


PTREC: PUT$ #FDBOUT, ,R1 ;R1 is needed to specify 
BCC GTREC ;the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSE$ RO ;Close the input file 
BCS ERROR 
CLOSE$ #FDBOUT ;Close the output file 
BCS ERROR 
EXIT$S ;Issue exit directive 
. END START 
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Appendix K 
Error Codes 


This appendix includes the source code for the following: 

e I/O error codes 

¢ Directive Status Word (DSW) error codes 

¢ I/O function codes 

This source code is located in [61,10]QIOMAC.MAC and is listed as follows: 
. TITLE QIOMAC - QIOSYM MACRO DEFINITION 


; DATE OF LAST MODIFICATION: 


: RYAN CHRISTOPHER 16-Nov-1984 


; #4 ALWAYS UPDATE THE FOLLOWING TWO LINES TOGETHER 
. IDENT /0375/ 
QI. VER=0375 


; COPYRIGHT (C) 1983, 1984 
; DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 


; THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
; SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
; INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
; ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
; MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
; SYSTEM AND TQ ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
; TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
; IN DEC. 
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; THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
; NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
; EQUIPMENT CORPORATION. 


; DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
: ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 


SHANE MICHAEL 1-OCT-73 


+ 

: MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES 

; AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL 
; DEFINITION) USE: 


; QlIosy$ ;DEFINE SYMBOLS 


: TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE: 
; QIOsy$ DEF$G ;SYMBOLS DEFINED GLOBALLY 


; THE MACRO CAN BE CALLED ONCE ONLY AND THEN 
; REDEFINES ITSELF AS NULL. 


-MACRO QIOSY$ $$$CBL,$$$MSG 
LIIF IDN,<$$$GBL>,<DEF$G>, .GLOBL QI.VER 
_IF IDN , <$$$MSG> , <DEF$S> 


$$$MAX=0 

$$MSG=1 

.IFF 

$$MSG=0 

.ENDC 

.MCALL  IOERR$ 

IOERR$  $$$GBL -I/0 ERROR CODES FROM HANDLERS, FCP, FCS 
.MCALL  DRERR$ 

DRERR$  $$$GBL -DIRECTIVE STATUS WORD ERROR CODES 
IF DIF ,<$$$MSG> , <DEF$S> 

.MCALL FILIO$ 

FILIO$  $$$GBL ‘DEFINE GENERAL I/0 FUNCTION CODES 
-MCALL  SPCIO$ 

SPCIO$  $$$GBL :DEVICE-DEPENDENT I/Q FUNCTION CODES 
.MACRO QIOSY$ ARG, ARG1 , ARG2 ;RECLAIM MACRO STORAGE 
.ENDM qQrosy$ 

.ENDC 


. ENDM QIosy$ 
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; DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES 

; IN THE FIRST WORD OF THE I/O STATUS BLOCK 

; THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE 

; BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FDB) 

‘ THE BYTE F.ERR+1i IS O IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE. 


-ENABL LC 
.MACRO  IDERR$ $$$GBL 
.MCALL .IOER. ,DEFIN$ 

IF IDN, <$$$GBL> , <DEF$G> 
.. .GBL=1 

.IFF 

.. .GBL=0 

.ENDC 


.IIF NDF , $$MSG , $$MSG=0 


; SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS 
- IOER. IE.BAD,-01.,<Bad parameters> 
.IOER. IE. IFC,-02.,<Invalid function code> 
-IOER. IE.DNR,-03.,<Device not ready> 
. IOER . TE.VER,-04.,<Parity error on device> 
. IOER. IE.ONP,-05.,<Hardware option not present> 
-IOER. IE.SPC,-06.,<Illegal user buffer> 
. IOER. IE.DNA,-07.,<Device not attached> 
-IOER. IE.DAA,-08.,<Device already attached> 
-IOER.~ -IE-DUN, -09.,;<Device-not~attachable> 
‘IOER.  IE.EOF,-10.,<End of file detected> 
-IOER. IE.EOV,-i1.,<End of volume detecteds 
-IOER. IE.WLK,-12.,<Write attempted to locked unit> 
-IOER. IE.DAOQ,-13.,<Data overrun> 
-IOER. IE.SRE,-14.,<Send/receive failure> 
- IOER. TE.ABO,-15.,<Request terminated> 
-I0ER. IE.PRI,-16.,<Privilege violation> 
- IOER . IE.RSU,-17.,<Shareable resource in use> 
-IOER. TE.OVR,-18.,<Illegal overlay request> 
-IQER. IE.BYT,-19.,<Odd byte count (or virtual address)> 
-IOER. IE.BLK,-20.,<Logical block number too large> 
. IOER. IE.MOD,-21.,<Invalid UDC module #> 
-IOER. IE.CON,-22.,<UDC connect error> 
. IOER. IE.BBE,-56.,<Bad block on device> 
-I0ER. IE.STK,-58.,<Not enough stack space (FCS or FCP)> 
- IOER. IE.FHE,-59.,<Fatal hardware error on device> 
-IQER. IE.EQT,-62.,<End of tape detected> 
-IOER. IE.OFL,-65.,<Device off line> 
-IOER. IE.BCC,-66.,<Block check, CRC, or framing error> 
- IOER. IE.NFW,-69.,<Path lost to partner> ;THIS CODE MUST BE ODD 
-IQER. IE.DIS,-69.,<Path lost to partner> ;DISCONNECTED (SAME AS NFW) 
-IOER. IE.PNT,-71.,<Partition/Region not in system> 
. IOER. IE.NDR,-72.,<No dynamic space available> ; SEE ALSO IE.UPN 
. IOER. IE.TMO,-95.,<Timeout on request> ; see also IS.TMO 
. IOER. TE.CNR,-96.,<Connection rejected> 
. IOER. IE.MII,-99.,<Media inserted incorrectly> 
-IOER. IE.SPI,-100.,<Spindown ignored> 
. IOER. IE.FER,-101.,<Forced error mark encountered> 
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; FILE PRIMITIVE CODES 


. IOER. 
. IOER. 
. IOER. 
- IOER . 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
- IOER. 
. IGER. 
.IOER. 
-IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
.IOER. 
. IOER. 


.NOD,-23.,<Caller's nodes exhausted> 
.DFU,-24.,<Device full> 

.IFU,-25.,<Index file full> 

.NSF ,-26.,<No such file> 

.LCK,-27.,<Locked from read/write access> 
.HFU,-28.,<File header full> 
.WAC,-29.,<Accessed for write> 

.CKS,-30.,<File header checksum failure> 
.WAT,-31.,<Attribute control list format error> 
.RER,-32.,<File processor device read error> 
.WER,-33.,<File processor device write error> 
.ALN,-34.,<File already accessed on LUN> 
.SNC,-35.,<File ID, file number check> 
.SQC,-36.,<File ID, sequence number check> 
.NLN,-37.,<No file accessed on LUN> 
.CLO,-38.,<File was not properly closed> 
.DUP,-57.,<ENTER - duplicate entry in directory> 
.BVR,-63.,<Bad version number> 

.BHD,-64.,<Bad file header> 

.EXP,-75.,<File expiration date not reached> 
.BIF,-76.,<Bad tape format> 
.ALC,-84.,<Allocation failure> 
.ULK,-85.,<Unlock error> 

.WCK ,-86. ,<Write check failure> 
.DSQ,-90.,<Disk quota exceeded> 
.PIO,-104.,<Deacess failed due to pending I/0> 


; FILE CONTROL SERVICES CODES 


. IOER. 
. IOER. 
. IOER. 
. IOER. 
.IOER. 
.IQER. 
. IOER. 
. IOER. 
. I0ER. 
. TOER. 
. IOER. 
.IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 


IE. 
IE. 
.NBK,-41.,<File exceeds space allocated, no blocks> 
.ILL,-42.,<Illegal operation on file descriptor block> 
.BTP,-43.,<Bad record type> 

-RAC,-44.,<Illegal record access bits set> 
-RAT,-45.,<Illegal record attributes bits set> 
-RCN,-46. ,<Illegal record number - too large> 
.2DV,-48.,<Rename - 2 different devices> 
.FEX,-49.,<Rename - new file name already in use> 
.BDR,-50.,<Bad directory file> 

.RNM,-51.,<Can't rename old file system> 

.BDI,-52. ,<Bad directory syntax> 

.FOP,-53.,<File already open> 

.BNM,-54.,<Bad file name> 

.BDV,-55.,<Bad device name> 

.NFI,-60.,<File ID was not specified> 
.I8SQ,-61.,<Illegal sequential operation> 
.NNC,-77.,<Not ANSI 'D' format byte count> 


NBF ,-39.,<OPEN - no buffer space available for file> 
RBG, -40. ,<Illegal record size> 


; NETWORK ACP, PSI, AND DECDATAWAY CODES 


K-4 Error Codes 


. IOER. 
- IOER. 
. IOER. 
. IOER. 
. IOER. 
. IOER. 
.IOER. 
. IOER. 
. IOER. 
. IOER. 
- IOER. 
. IOER. 


; ICS/ICR ERROR 


. IOER. 
- IOER. 
. IOER . 


IE. 
IE. 
-URJ,-73.,<Connection rejected by user> 
IE. 
IE. 
IE. 


IE 


IE 


IE 


NNN ,-68.,<No such node> 
BLB,-70.,<Bad logical buffer> 


NRJ,-74.,<Connection rejected by network> 
NDA,-78.,<No data available> 
IQU,-91.,<Inconsistent qualifier usage> 


-RES,-92.,<Circuit reset during operation> 
IE. 
IE. 


TML,-93.,<Too many links to task> 
NNT,~94.,<Not a network task> 


.UKN,-97.,<Unknown name> 
IE. 
IE. 


IRR,-102. ,<Insufficient resources at remote node> 
SIU,-103.,<Service in use> 


CODES 


IE. 
IE. 
IE. 


; TTY ERROR CODES 


. IOER. 
. IOER. 


IE 


NLK,-79.,<Task not linked to specified ICS/ICR interrupts> 
NST ,-80.,<Specified task not installed> 
FLN,-81.,<Device offline when offline request was issued> 


.IES,-82.,<Invalid escape sequence> 
IE. 


PES ,-83.,<Partial escape sequence> 


; RECONFIGURATION CODES 


. IOER. 
. IOER. 
. IQER. 


IE 


; PCL ERROR CODES 


. IOER. 
. IOER . 
- IOER. 


IE 


TE 


.ICE,-47.,<Internal consistancy error> 
IE. 
IE. 


ONL,-67.,<Device online> 
SZE,-98.,<Unable to size device> 


.NTR,-87.,<Task not triggered> 
IE. 


REJ,-88.,<Transfer rejected by receiving CPU> 


.FLG,-89. ,<Event flag already specified> 


; SUCCESSFUL RETURN CODES--- 


DEFIN$ 
DEFIN$ 
DEF IN$ 
DEFIN$ 
DEFIN$ 


DEFIN$ 


DEF IN$ 


Is. 
Is. 
IS. 


IS. 


Is 


Is. 


Is 


PND, +00. ;OPERATION PENDING 
SUC, +01. ;OPERATION COMPLETE, SUCCESS 
RDD, +02. ;FLOPPY DISK SUCCESSFUL COMPLETION 
;O0F A READ PHYSICAL, AND DELETED 
;DATA MARK WAS SEEN IN SECTOR HEADER 
TNC, +02. ; (PCL) SUCCESSFUL TRANSFER BUT MESSAGE 
;TRUNCATED (RECEIVE BUFFER TOO SMALL). 
CHW, +04. ; (IBM COMM) DATA READ WAS RESULT OF 
; IBM HOST CHAINED WRITE OPERATION 
BV, +05. ; (A/D READ) AT LEAST ONE BAD VALUE 


;WAS READ (REMAINDER MAY BE GOOD). 
;BAD CHANNEL IS INDICATED BY A 
;NEGATIVE VALUE IN THE BUFFER. 
DAO, +02. ;SUCCESSFUL BUT WITH DATA OVERRUN 
; (NOT TO BE CONFUSED WITH IE.DAD) 


Error Codes 


; TTY SUCCESS CODES 


, 


DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS 
DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS. 
DEFIN$ IS. 


; Professional Bisync Success Codes 


CR , <15*400+1> 
ESC , <33*400+1> 
CC , <3*400+1> 
ESQ , <233+#400+1> 
PES , <200+400+1> 


.EOT , <4*400+1> 


TAB ,<11*400+1> 
TMO,+2. 
OOB +3. 
TMM, +4. 


;CARRIAGE RETURN WAS TERMINATOR 

;ESCAPE (ALTMODE) WAS TERMINATOR 

;CONTROL-C WAS TERMINATOR 

;ESCAPE SEQUENCE WAS TERMINATOR 

;PARTIAL ESCAPE SEQUENCE WAS TERMINATOR 
;EOT WAS TERMINATOR (BLOCK MODE INPUT) 

;TAB WAS TERMINATOR (FORMS MODE INPUT) 
;REQUEST TIMED OUT 

;QUT OF BAND TERMINATOR (TERM IN HIGH BYTE) 
;READ COMPLETED, MANAGEMENT MODE SEQ RCVD 


DEFIN$ IS.RVI,+2. ; DATA SUCC. XMITTED; HOST ACKED W/RVI 
DEFIN$ IS.CNV,+3. ; DATA SUCC. XMITTED; HOST ACKED W/CONVERSATION 
DEFIN$ IS.XPT,+5. ; DATA SUCC. RECVD IN TRANSPARENT MODE 


; Professional Bisync Abort Codes 


; These codes are returned in the high byte of the first word of the IOSB 
; when the low byte contains IE. ABO. 


DEFIN$ SB. 
DEFIN$ SB. 
DEFIN$ SB. 
DEFIN$ SB. 
DEFIN$ SB. 
DEFIN$ SB. 
DEFIN$ SB. 


Sk 


; THE NEXT AVAILABLE ERROR NUMBER IS: 


2K 


KIL,-1. ; ABORTED BY I0.KIL 

ACK,-2. ; ABORTED BECAUSE TOO MANY ACKS RECD OUT OF SEQ 
NAK,-3. ; ABORTED BECAUSE NAK THRESHOLD EXCEEDED 
ENQ,-4. ; ABORTED BECAUSE ENQ THRESHOLD EXCEEDED 
BOF,-5. ; ABORTED BECAUSE OF I0.RLB BUFFER OVERFLOW 
TMO,-6. ; ABORTED BECAUSE OF TIMEOUT 

DIS,-7. ; ABORTED BECAUSE HOST DISCONNECTED W/ DLE, EOT 


_IF EQ, $$MSG 
.MACRO IOERR$ A 
. ENDM IOERR$ 

. ENDC 

.ENDM IOERR$ 


K-6 Error Codes 


-101. 


; DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD 


FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR 
OF THE FILE DESCRIPTOR BLOCK (FDB). TO DISTINGUISH THEM FROM THE 
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE 
F.ERR+1 IN THE FDB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE. 


.MACRO 
.MCALL 
.IF 
...GBL=1 
.IFF 

.. -GBL=0 
. ENDC 
.IIF 


DRERR$ 
-QIOE. ,DEFIN$ 
IDN ,<$$$GBL> , <DEF$G> 


$$$GBL 


NDF , $$MSG , $$MSG=0 


; STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD 


-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
.QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QIOE. 
-QTOE. 
-QIOE. 
-QIOE. 


IE. 
TE. 
.PTS,-03. 
.UNS, ~04. 
-ULN, -05. 
.HWR,-06. 
.ACT,-07. 
.ITS,-08. 
-FIX,-09. 
.CKP,-10. 
.TCH,-11. 
-RBS,-15. 
-PRI,-16. 
-RSU,-17. 
-NSW,-18 
.ILV,-19 
.ITN,-20 
-LNF,-21 


UPN,-O1 
INS ,-02 


., <Insufficient dynamic storage> ; SEE ALSO IE.NDR 
., <Specified task not installed> 
»<Partition too small for task> 
»<Insufficient dynamic storage for send> 
,<Un-assigned LUN> 

»<Device handler not resident> 

,<Task not active> 

»<Directive inconsistent with task state> 
,<Task already fixed/unfixed> 

,<Issuing task not checkpointable> 

,<Task is checkpointable> 

,<Receive buffer is too small> 
,<Privilege violation> 

»<Resource in use> 

., <No swap space available> 

. “Illegal vector specified> 

.,<Invalid table number> 

.,<Logical name not found> 


Error Codes K-7 


-QIOE. JE.AST,-80.,<Directive issued/not issued from AST> 
-QIOE. IE.MAP,-81.,<Illegal mapping specified> 

.QIOE. IE.IOP,-83.,<Window has 1/0 in progress> 

-QIOE. IE.ALG,-84.,<Alignment error> 

.QIOE. IE.WOV,-85.,<Address window allocation overflow> 
.QIOE. IE.NVR,-86.,<Invalid region. ID> 

-QIOE. IE.NVW,-87.,<Invalid address window ID> 

-QIOE. IE.ITP,-88.,<Invalid TI parameter> 

QIOE. IE.IBS,-89.,<Invalid send buffer size ( .GT. 255 .)> 
-QIOE. IE.LNL,-90.,<LUN locked in use> 

.QIOE. IE.1UI,-91.,<Invalid UIC> 

.QIOE. IE. IDU,-92.,<Invalid device or unit> 

-QIOE. IE.ITI,-93.,<Invalid time parameters? 

.QIOE. IE.PNS,-94.,<Partition/region not in system> 
.QIOE. IE.IPR,-95.,<Invalid priority ( .GT. 250.)> 

.QIOE. IE.ILU,-96.,<Invalid LUN> 

.QIOE. IE. IEF ,-97.,<Invalid event flag ( .GT. 64.)> 
-QI0E. IE.ADP,-98.,<Part of DPB out of user's space? 
.QIOE. IE.SDP,-99.,<DIC or DPB size invalid> 


- SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD 


DEFIN$ IS.CLR,O ;EVENT FLAG WAS CLEAR 
-FROM CLEAR EVENT FLAG DIRECTIVE 
DEFIN$ IS.SET,2 ;EVENT FLAG WAS SET 
-FROM SET EVENT FLAG DIRECTIVE 
DEFIN$¢ IS.SPD,2 ;TASK WAS SUSPENDED 
DEFIN$ IS.SUP,3 ;LOGICAL NAME SUPERSEDED 
DEFIN$ IS.WAT,4 : OPERATION INITIATED, WAIT FOR COMPLETION 


:FROM "VAX-11 RSX" RMS-21 ELEP$ DIRECTIVE 


.IF EQ, $$MSG 
.MACRO DRERR$ A 
.ENDM DRERR$ 
.ENDC 

.ENDM DRERR$ 


K-8 Error Codes 


> 


-MACRO 
-MCALL 
IF 

.IFF 

. . .GBL=0 
. ENDC 


FILIO$ $$$GBL 
.WORD . , DEFIN$ 


; DEFINE THE GENERAL 1/0 FUNCTION CODES - DEVICE INDEPENDENT 


IDN , <$$$GBL> , <DEF$G> 


GENERAL I/O QUALIFIER BYTE DEFINITIONS 


-WORD. 
- WORD. 
. WORD. 
. WORD. 
. WORD. 


EXPRESS QUEUE 


.WORD. 
-WORD. 
. WORD. 
- WORD. 
. WORD. 
- WORD. 


IQ.X,001,000 
IQ.Q, 002,000 
IQ.S,004,000 
IQ. UMD, 004 ,000 
IQ. LCK, 200,000 


COMMANDS 


I0.KIL,012,000 
I0.RDN ,022,000 
I0.UNL, 042,000 
I0.LTK,050,000 
IO.RTK,060,000 
I0.SET,030,000 


GENERAL DEVICE DRIVER CODES 


. WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
- WORD. 


I0.WLB,000,001 
I0.RLB ,000 ,002 
Id. LOV,010,002 
I0.LDO0, 110,002 
I0. ATT ,000 , 003 
I0. DET, 000 ,004 


DIRECTORY PRIMITIVE CODES 


. WORD. 
-WORD. 
. WORD. 


IO.FNA,000,011 
IO. RNA ,000,013 
I0.ENA,000,014 


;NO ERROR RECOVERY 

;QUEUE REQUEST IN EXPRESS QUEUE 
+;SYNONYM FOR IQ.UMD 

;USER MODE DIAGNOSTIC STATUS REQUIRED 
;MODIFY IMPLIED LOCK FUNCTION 


:KILL CURRENT REQUEST 

31/0 RUNDOWN 

;UNLOAD I/O HANDLER TASK 
;LOAD A TASK IMAGE FILE 
;RECORD A TASK IMAGE FILE 
;SET CHARACTERISTICS FUNCTION 


;WRITE LOGICAL BLOCK 

;READ LOGICAL BLOCK 

;LOAD OVERLAY (DISK DRIVER) 
;LOAD D-SPACE OVERLAY (DISK) 
; ATTACH A DEVICE TO A TASK 
;DETACH A DEVICE FROM A TASK 


;FIND FILE NAME IN DIRECTORY 
;REMOVE FILE NAME FROM DIRECTORY 
;ENTER FILE NAME IN DIRECTORY 


Error Codes 


K-9 


; FILE 


PRIMITIVE CODES 


.WORD. IO0.CLN,000,007 ;CLOSE OUT LUN 

-WORD. IO.ULK,000,012  ;UNLOCK BLOCK 

-WORD. IO0.ACR,000,015 ;ACCESS FOR READ 
-WORD. IO.ACW,000,016  ;ACCESS FOR WRITE 
.WORD. IO0.ACE,000,017  ;ACCESS FOR EXTEND 
-WORD. IO.DAC,000,020 ;DE-ACCESS FILE 

-WORD. IO.RVB,000,021  ;READ VIRITUAL BLOCK 
.WORD. IO0.WVB,000,022 ;WRITE VIRITUAL BLOCK 
-WORD. IO0.EXT,000,023 ;EXTEND FILE 

.WORD. IO.CRE,000,024 ;CREATE FILE 

-WORD. IO.DEL,000,025 ;DELETE FILE 

-WORD. IO.RAT,000,026 ;READ FILE ATTRIBUTES 
.WORD. IO.WAT,000,027 ;WRITE FILE ATTRIBUTES 
.WORD. IO.APV,010,030 ;PRIVILEGED ACP CONTROL 
.WORD. IO0.APC,000,030 ;ACP CONTROL 

.MACRO FILIO$ A 

.ENDM FILIO$ 

.ENDM FILIO$ 


; DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL DEVICES 


. MACRO SPCIO$ $$$GBL 
.MCALL .WORD. , DEFIN$ 

.IF IDN ,<$$$GBL> , <DEF$G> 
...GBL=1 

. IFF 

.. .GBL=0 

. ENDC 


; 1/0 FUNCTION CODES FOR SPECIFIC DEVICE-DEPENDENT FUNCTIONS 


. WORD. IO.WLV,100,001 ;(DECTAPE) WRITE LOGICAL REVERSE 

- WORD. IO.WLS,010,001 ;(COMM.) WRITE PRECEDED BY SYNC TRAIN 
- WORD. I0.WNS,020,001 ;(COMM.) WRITE, NO SYNC TRAIN 

- WORD. IO.WAL,010,001 ;(TTY) WRITE PASSING ALL CHARACTERS 

. WORD. I0.WMS,020,001 ;(TTY) WRITE SUPPRESSIBLE MESSAGE 

- WORD. I0.CCO,040,001 ;(TTY) WRITE WITH CANCEL CONTROL-O 

. WORD. IO.WBT,100,001 ; (TTY) WRITE WITH BREAKTHROUGH 

- WORD. IO.WLT,010,001 ;(DISK) WRITE LAST TRACK 

- WORD. IO.WLC,020,001 ;(DISK) WRITE LOGICAL W/ WRITECHECK 

. WORD. I0.WPB,040,001 ;(DISK) WRITE PHYSICAL BLOCK 

. WORD. IO.WDD,140,001 ;(FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA 
. WORD. I0.RSN,140,002 ;(MSCP DISK) READ VOLUME SERIAL NUMBER 
. WORD . IO.RLV,100,002 ;(MAGTAPE,DECTAPE) READ REVERSE 

. WORD. IO.RST,001,002 ;(TTY) READ WITH SPECIAL TERMINATOR 

. WORD. I0.RAL,010,002 ;(TTY) READ PASSING ALL CHARACTERS 

- WORD. I0.RNE,020,002 ; (TTY) READ WITHOUT ECHO 

- WORD. IO.RNC,040,002 ;(TTY) READ - NO LOWERCASE CONVERT 

- WORD. IO.RTM,200,002 ;(TTY) READ WITH TIME-OUT 

- WORD. I0.RDB,200,002 ;(CARD READER) READ BINARY MODE 

. WORD. I0.SCF,200,002 ;(DISK) SHADOW COPY FUNCTION 

. WORD. IO0.RHD,010,002 ;(COMM.) READ, STRIP SYNC 


K-10 Error Codes 


- WORD. 
- WORD. 
- WORD. 
- WORD. 
. WORD. 
- WORD. 
. WORD. 
. WORD. 
. WORD. 
. WORD. 
-WORD. 
-WORD. 
. WORD. 
- WORD . 
- WORD. 
- WORD. 
-WORD. 
- WORD . 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD . 
.WORD . 
. WORD. 
. WORD. 
. WORD. 
- WORD. 
-WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD. 
. WORD. 
- WORD. 
- WORD. 
- WORD . 
- WORD. 
- WORD. 


.RNS ,020 ,002 
.CRC ,040 ,002 
-RPB ,040 ,002 
-RDF , 240 ,002 
-RLC 020,002 
-ATA,010 ,003 
.GTS ,000 , 005 
-R1C,000 ,005 
- INL, 000,005 
-TRM,010,005 
-RWD ,000 ,005 
. SPB 020,005 
.RPL 020,005 
. SPF ,040 ,005 
.STC, 100,005 
.SMD, 110,005 
.SEC, 120,005 
-RWU, 140,005 
-5M0, 160,005 
-HNG ,000 ,006 
-HLD , 100 ,006 
. BRK , 200 ,006 
-RBC ,000 ,006 
-MOD ,000 , 006 
-HDX ,010 , 006 
-FDX ,020 , 006 
- SYN ,040 , 006 
- EOF ,000 , 006 
- ERS ,020 , 006 
. DSE , 040 , 006 
-RTC ,000 ,007 
.SA0 ,000 ,010 
.SS0,000 ,011 
-RPR,0OO ,011 
-MSO,000 ,012 
-RIT,001 ,012 
- SLO ,000 ,013 
-MLO,000 ,014 
. LED ,000 ,024 
-5D0 ,000 ,025 
.5DI,000 , 026 
-5CS ,000 , 026 
-REL ,000 ,027 
. MCS ,000 ,027 
. ADS ,000 , 030 
.CCI ,000 ,030 
. LOD ,000 ,030 
-MDT ,000 ,031 
-DCI ,000 ,031 
-PAD ,000 ,031 
.RPP ,010 ,000 


;(COMM.) READ, DON'T STRIP SYNC 
;(COMM.) READ, DON'T CLEAR CRC 

; (DISK) READ PHYSICAL BLOCK 

; (DISK) READ DISK FORMAT 

; (DISK ,MAGTAPE) READ LOGICAL W/ READCHECK 
; (TTY) ATTACH WITH ASTS 

; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS 
; (AFC, ADO1,UDC) READ SINGLE CHANNEL 
;(COMM.) INITIALIZATION FUNCTION 
;(COMM.) TERMINATION FUNCTION 

; (MAGTAPE ,DECTAPE) REWIND 

; (MAGTAPE) SPACE "N" BLOCKS 

; (DISK) REPLACE LOGICAL BLOCK (RESECTOR) 
; (MAGTAPE) SPACE "N" EOF MARKS 

;SET CHARACTERISTIC 

; (FLOPPY DISK) SET MEDIA DENSITY 
;SENSE CHARACTERISTIC 

; (MAGTAPE ,DECTAPE) REWIND AND UNLOAD 

; (MAGTAPE) MOUNT & SET CHARACTERISTICS 
; (TTY) HANGUP DIAL-UP LINE 

; (TMS) HANGUP BUT LEAVE LINE ON HOLD 

; (PRO/TTY) SEND SHORT OR LONG BREAK 
;READ MULTICHANNELS (BUFFER DEFINES CHANNELS) 
;(COMM.) SETMODE FUNCTION FAMILY 
;(COMM.) SET UNIT HALF DUPLEX 

;(COMM.) SET UNIT FULL DUPLEX 

;(COMM.) SPECIFY SYNC CHARACTER 

; (MAGTAPE) WRITE EOF 

; (MAGTAPE) ERASE TAPE 

; (MAGTAPE) DATA SECURITY ERASE 

;READ CHANNEL - TIME BASED 

; (UDC) SINGLE CHANNEL ANALOG OUTPUT 

; (UDC) SINGLE SHOT, SINGLE POINT 

; (TTY) READ WITH PROMPT 

; (UDC) SINGLE SHOT, MULTI-POINT 

; (TTY) READ WITH TERMINATOR TABLE 

; (UDC) LATCHING, SINGLE POINT 

; (UDC) LATCHING, MULTI-POINT 

;(LPS11) WRITE LED DISPLAY LIGHTS 
;(LPS11) WRITE DIGITAL OUTPUT REGISTER 
;(LPS11) READ DIGITAL INPUT REGISTER 

; (UDC) CONTACT SENSE, SINGLE POINT 
;(LPS11) WRITE RELAY 

; (UDC) CONTACT SENSE, MULTI-POINT 

; (LPS11) SYNCHRONOUS A/D SAMPLING 

; (UDC) CONTACT INT - CONNECT 

;(LPA11) LOAD MICROCODE 

;(LPS11) SYNCHRONOUS DIGITAL INPUT 
;(UDC) CONTACT INT - DISCONNECT 

; (PSI) DIRECT CONTROL OF X.29 PAD 

; (PSI) RESET PAD PARAMETERS SUBFUNCTION 


Error Codes 


K-11 


. WORD . I0.XMT,000,031 ;(COMM.) TRANSMIT SPECIFIED BLOCK WITH ACK 

- WORD. I0.XNA,010,031 ;(COMM.) TRANSMIT WITHOUT ACK 

- WORD. IO.INI,000,031 ;(LPA11) INITIALIZE 

- WORD . I0.HIS,000,032 ;(LPS11) SYNCHRONOUS HISTOGRAM SAMPLING 

. WORD. I0.RCI,000,032 ;(UDC) CONTACT INT - READ 

. WORD. IO.RCV,000,032 ;(COMM.) RECEIVE DATA IN BUFFER SPECIFIED 

. WORD. I0.CLK,000,032 ;(LPA11) START CLOCK 

-WORD. I0.CSR,000,032 ;(BUS SWITCH) READ CSR REGISTER 

. WORD. I0.MDO0,000,033 ;(LPS11) SYNCHRONOUS DIGITAL OUTPUT 

- WORD. I0.CTI,000,033 ; (UDC) TIMER - CONNECT 

.WORD . I0.CON,000,033 ;(COMM.) CONNECT FUNCTION 
;(VT11) - CONNECT TASK TO DISPLAY PROCESSOR 
; (BUS SWITCH) CONNECT TO SPECIFIED BUS 
;(COMM./PRO) DIAL TELEPHONE AND ORIGINATE 

- WORD. I0.0RG,010,033 ;(COMM.) INITIATE CONNECTION IN ORIGINATE MODE 

- WORD. I0.ANS,020,033 ;(COMM.) INITIATE CONNECTION IN ANSWER MODE 

-WORD. I0.STA,000,033 ;(LPA11) START DATA TRANSFER 
; (XJDRV) - SHOW STATE 

- WORD. I0.DTI,000,034 ;(UDC) TIMER - DISCONNECT 

- WORD. I0.DIS,000,034 ;(COMM.) DISCONNECT FUNCTION 
;(VT11) - DISCONNECT TASK FROM DISPLAY PROCESSOR 
; (BUS SWITCH) SWITCHED BUS DISCONNECT 

. WORD. IO.MDA,000,034 ;(LPS11) SYNCHRONOUS D/A OUTPUT 

- WORD. I0.DPT,010,034 ;(BUS SWITCH) DISCONNECT TO SPECIF PORT NO. 

- WORD. IO.RTI,000,035 ;(UDC) TIMER - READ 

- WORD. I0.CTL,000,035 ;(COMM.) NETWORK CONTROL FUNCTION 

- WORD. I0.STP,000,035 ;(LPSi1,LPA11) STOP IN PROGRESS FUNCTION 
;(VT11) - STOP DISPLAY PROCESSOR 

- WORD. IO0.SWI,000,035 ;(BUS SWITCH) SWITCH BUSSES 

.WORD. I0.CNT,000,036 ;(VT11) - CONTINUE DISPLAY PROCESSOR 
; (XJDRV) - SHOW COUNTERS 

-WORD. I0.ITI,000,036 ;(UDC) TIMER - INITIALIZE 


; EXTENDED I/0 FUNCTION 


- WORD. I0.EIO,000,037 ; (TTY) TSA EXTENDED I/D 


; PRO 300 SERIES BITMAP FUNCTIONS 


: NOTE: THESE FUNCTIONS ARE FOR DEC USE ONLY AND ARE SUBJECT TO CHANGE 


. WORD. I0.RSD,030,014 ; READ SPECIAL DATA 
. WORD. I0.WSD,010,013 ; WRITE SPECIAL DATA 
DEFIN$ SD.TXT,O ; TEXT DATA TYPE FOR SPECIAL DATA 
DEFIN$ SD.GDS,1 ; GIDIS DATA TYPE FOR SPECIAL DATA 


; PROFESSIONAL 300 BISYNC DRIVER (XJDRV) FUNCTIONS 


. WORD . SB.PRT,020,003 ; ATTACH AS A PRINTER 

. WORD . SB.CLR,010,036 ; CLEAR COUNTERS (I0.CNT SUBFUNCTION) 

. WORD. SB.RDY,010,033 ; SET DEVICE STATE READY (I0.STA SUBFUNC) 
. WORD. SB.NRD,020,033 ; SET DEVICE STATE NOT READY 

. WORD. I0.LBK,000,035 ; PERFORM LOOPBACK TEST 

. WORD. SB.CBL,010,035 ; PERFORM CABLE LOOPBACK TEST 

. WORD. SB.CLK,020,035 ; DEVICE PERFORMS LINE CLOCKING 
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; COMMUNICATIONS FUNCTIONS 


. WORD. 
. WORD. 
. WORD . 
- WORD. 
. WORD. 
.WORD. 
- WORD. 
. WORD . 
. WORD. 
- WORD . 
.WORD . 
-WORD. 
- WORD. 
. WORD. 
- WORD. 
- WORD. 
- WORD. 


IO. 
Id. 


10 


Id. 
Io. 
Io. 
Io. 
I0. 
10. 
Io. 
Id. 
Id. 
Io. 
Io. 
Io. 
Io. 
10. 


CPR,010 ,033 
CAS ,020 , 033 
.CRJ ,040 ,033 
CBO ,110,033 
CTR, 210,033 
GNI,010,035 
GLI, 020 ,035 
GLC ,030 ,035 
GRI , 040,035 
GRC , 050,035 
GRN , 060 ,035 
CSM 070,035 
CIN, 100,035 
SPW,110,035 
CPW, 120,035 
NLB, 130,035 
DLB, 140,035 


; ICS/ICR 1/0 FUNCTIONS 


- WORD. 
. WORD. 
- WORD . 
. WORD. 
- WORD. 
. WORD. 
. WORD. 
- WORD . 
-WORD. 
- WORD . 
- WORD. 
-WORD. 
- WORD. 
. WORD. 


. CTY ,000 , 007 
.DTY,000,015 
.LDI, 000,016 
-UDI, 010,023 
-LTI,000,017 
.UTI ,020 , 023 
- LTY ,000 ,020 
.UTY ,030 , 023 
- LKE ,000 , 024 
-UER ,040, 023 
.NLK ,000 , 023 
.ONL ,000 , 037 
.FLN 000,025 
-RAD ,000 ,021 


; IPi1 I/0 FUNCTIONS 


- WORD . 
. WORD. 
.WORD. 
. WORD. 
- WORD. 
- WORD. 
- WORD. 
- WORD . 
. WORD. 
. WORD. 
- WORD. 
- WORD. 


I0 
Id 
10 
Io 
To 
Io 
10 


Io. 


Io 
Io 
Io 
Io 


.MAO 010,007 
-LEI 010,017 
-RDD , 010,020 
- RMT, 020,020 
.LSI 000,022 
.UEI 050,023 
.USI ,060 ,023 
CSI, 000,026 
.DSI ,000 ,027 
-RAM, 000,032 
-RLK ,000,013 
-EBT,000,011 


; PCL11 I/O FUNCTIONS 


;CONNECT NO TIME-OUTS 
;CONNECT WITH AST 

;CONNECT REJECT 

;BOOT CONNECT 

; TRANSPARENT CONNECT 

:GET NODE INFORMATION 

;GET LINK INFORMATION 

:GET LINK INFO CLEAR COUNTERS 
;GET REMOTE NODE INFORMATION 
;GET REMOTE NODE ERROR COUNTS 
;GET REMOTE NODE NAME 

;CHANGE SOLO MODE 

;CHANGE CONNECTION INHIBIT 
;SPECIFY NETWORK PASSWORD 
;CHECK NETWORK PASSWORD 

;NSP LOOPBACK 

;DDCMP LOOPBACK 


;CONNECT TO TERMINAL INTERRUPTS 
;DISCONNECT FROM TERMINAL INTERRUPTS 
;LINK TO DIGITAL INTERRUPTS 

;UNLINK FROM DIGITAL INTERRUPTS 

;LINK TO COUNTER MODULE INTERRUPTS 
;UNLINK FROM COUNTER MODULE INTERRUPTS 
;LINK TO REMOTE TERMINAL INTERRUPTS 
;UNLINK FROM REMOTE TERMINAL INTERRUPTS 
;LINK TO ERROR INTERRUPTS 

;UNLINK FROM ERROR INTERRUPTS 

;UNLINK FROM ALL INTERRUPTS 


;UNIT ONLINE 


;UNIT OFFLINE 
;READ ACTIVATING DATA 


;MULTIPLE ANALOG OUTPUTS 

;LINK EVENT FLAGS TO INTERRUPT 
;READ DIGITAL DATA 

;READ MAPPING TABLE 

;LINK TO DSI INTERRUPTS 
;UNLINK EVENT FLAGS 

;UNLINK FROM DSI INTERRUPTS 
;CONNECT TO DSI INTERRUPTS 
;DISCONNECT FROM DSI INTERRUPTS 
;READ ANALOG MAPPING TABLES 
;READ RESOURCE LINKAGES 

;CHECK EBIT STATUS 
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- WORD. IO.ATX,000,001 ;ATTEMPT TRANSMISSION 

. WORD. IO.ATF,000,002 ;ACCEPT TRANSFER 

- WORD. I0.CRX,000,031 ;CONNECT FOR RECEPTION 

- WORD. IO0.DRX,000,032 ;DISCONNECT FROM RECEPTION 
- WORD . I0.RTF,000,033 ;REJECT TRANSFER 


.MACRO SPCIO$ A 
.ENDM SPCIO$ 
.ENDM SPCIO$ 


: DEFINE THE I/O CODES FOR USER-MODE DIAGNOSTICS. ALL DIAGNOSTIC 
- FUNCTIONS ARE IMPLEMENTED AS A SUBFUNCTION OF 1/0 CODE 10 (OCTAL) . 


.MACRO UMDIO$ $$$GBL 
-MCALL .WORD. , DEFIN$ 
.IF IDN <$$$GBL>,<DEF$G> 
.. .GBL=1 
.IFF 
.. .GBL=0 
.ENDC 


: DEFINE THE GENERAL USER-MODE I/0 QUALIFIER BIT. 


-WORD. IQ.UMD,004,000 ;USER-MODE DIAGNOSTIC REQUEST 


; DEFINE USER-MODE DIAGNOSTIC FUNCTIONS. 


-WORD. IO.HMS,000,010 ;(DISK) HOME SEEK OR RECALIBRATE 

.WORD. IO.BLS,010,010 ;(DISK) BLOCK SEEK 

.WORD . I0.OFF,020,010 ;(DISK) OFFSET POSITION 

. WORD. IO.RDH,030,010 ; (DISK) READ DISK HEADER 

.WORD. I0.WDH,040,010 ;(DISK) WRITE DISK HEADER 

. WORD. IO.WCK,050,010 ;(DISK) WRITECHECK (NONTRANSFER) 

.WORD . IO.RNF,060,010 ;(DECTAPE) READ BLOCK NUMBER FORWARD 
.WORD. IO.RNR,O70,010 ;(DECTAPE) READ BLOCK NUMBER REVERSE 
-WORD. IO.LPC,100,010 ;(MAGTAPE) READ LONGITUDINAL PARITY CHAR 
. WORD . IO.RTD,120,010 ;(DISK) READ TRACK DESCRIPTOR 

. WORD. IO0.WTD,130,010 ;(DISK) WRITE TRACK DESCRIPTOR 

- WORD. IO.TDD,140,010 ;(DISK) WRITE TRACK DESCRIPTOR DISPLACED 
.WORD. IO0.DGN,150,010 ;DIAGNOSE MICRO PROCESSOR FIRMWARE 
-WORD. IO.WPD,160,010 ;(DISK) WRITE PHYSICAL BLOCK 

.WORD. IO.RPD,170,010 ; (DISK) READ PHYSICAL BLOCK 

. WORD. IO.CER,200,010 ; (DISK) READ CE BLOCK 

.WORD. I0.CEW,210,010 ; (DISK) WRITE CE BLOCK 


; MACRO REDEFINITION TO NULL 


.MACRO UMDIO$ A 
. ENDM 


K-14 Error Codes 


, 


.ENDM UMDIO$ 


HANDLER ERROR CODES RETURNED IN I/0 STATUS BLOCK ARE DEFINED THROUGH THIS 


; MACRO, WHICH THEN CONDITIONALLY INVOKES THE MESSAGE-GENERATING MACRO 
; FOR THE QIOSYM.MSG FILE 


.MACRO -IOER. SYM,LO,MSG 
DEFIN$ SYM,LO 

.IF GT, $$MSG 

-MCALL ~~ .IOMG. 

-IOMG. SYM,LO,<MSG> 

. ENDC 

.ENDM - IDER. 


I/O ERROR CODES ARE DEFINED THROUGH THIS MACRO, WHICH THEN INVOKES THE 


; ERROR MESSAGE-GENERATING MACRO; ERROR CODES -129 THROUGH -256 
; ARE USED IN THE QIOSYM.MSG FILE 


.MACRO -QIOE. SYM,LO,MSG 
DEFIN$ SYM,LO 
.IF GT, $$MSG) 


.MCALL - IOMG. 

.IOMG. SYM, <LO-128.>,<MSG> 
.ENDC 

.ENDM -QIOE. 


; CONDITIONALLY GENERATE DATA FOR WRITING A MESSAGE FILE 


-MACRO .IOMG. SYM, LO,MSG 


- WORD -*0<L0> 

-ENABL LC 

-ASCIZ “MSG* 

-DSABL LC 

-EVEN 

. TIF LT, “O<$$$MAX+<LO>>, $$$MAX=-~0<LO> 
. ENDM . TOMG. 


; DEFINE THE SYMBOL SYM WHERE LO IS THE LOW-ORDER BYTE, HI IS THE HIGH BYTE 


-MACRO -WORD. SYM,LO,HTI 
DEFIN$ SYM,<HI*400+L0> 
.ENDM - WORD . 

-DSABL LC 
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Appendix L 
RSX-11M-PLUS and Micro/RSX FCS Library Options 


L.1 FCS Library Options 


During system generation, the system manager has the option of selecting one of several File 
Control Services (FCS) libraries as the default FCS library. You can replace the default library 
in SYSLIB with one of the other libraries shown in Table L-1 by using the /RP switch to 
the Librarian Utility Program (LBR). Refer to the RSX-11M-PLUS Utilities Manual for more 
information. Table L-1 contains a brief description of the FCS libraries that are available with 
each RSX-11M-PLUS and Micro/RSX system. 


Table L-1: FCS Library Descriptions 


FCS Library Option Description 

[1,1]FCS.OBJ Includes standard FCS routines. Distributed and included in 
SYSLIB.OLB as the default FCS library. 

[1,1]FCSMTA.OBJ Includes standard FCS routines, plus American National Standards 


Institute (ANSI) magnetic tape support and “big buffering” 
(see Chapter 2 for block buffer size override specification). 
Distributed and included as the default FCS library routines for 
RSX-11M-PLUS and Micro/RSX. 


[1,1]FCSMBF.OBJ Provides multibuffering support, big buffering support, and ANSI 
magnetic tape support in addition to the standard FCS routines. 


L.2 .FCTYP 


The FCS routine .FCTYP returns a description of the FCS conditional assembly parameters that 
were set when FCS was built. 
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Format 
CALL .FCTYP 
There are no input parameters. 


The information is returned in R1. The bits set in the mask word returned in R1 correspond to 
the conditional assembly parameters shown in Table L-2. 


Table L-2: .FCTYP Values 


Conditional 
Assembly Symbol RI Bit Mask Symbol Meaning 


R$$ANI FT.ANI ANSI magnetic tape support 
R$$BBF FT.BBF Big buffer support 
RSSMBF FT.MBF Multibuffer support 


a 
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A 


Access control parameter 
F11ACP, H-12 

Access shared function, 2-14 

Access shared read function, 1-14 

Access shared write function, 1-13 

ACP 

error return, H-3 

IE.ABO, H-3 
IE.ALC, H-3 
IE.ALN, H-3 
IE.BAD, H-3 
IE.BDR, H-4 
IE.BTP, H-4 
IE.BVR, H-4 
IE.BYT, H-4 
IE.CKS, H-4 
IE.CLO, H-4 
IE.DFU, H-4 
IE.DUP, H-4 
IE.EOF, H-4 
IE.HFU, H-4 
IE.IFC, H-4 
IE.IFU, H-4 
IE.LCK, H-5 
IE.LUN, H-5 
IE.NOD, H-5 
IE.NSF, H-5 
IE.OFL, H-5 
IE.PRI H-5 
IE.RER, H-5 
IE.SNC, H-5 
IE.SPC, H-5 
IE.SQC, H-5 
IE.WAC, H-5 
IE.WAT, H-5 
IE.WER, H-6 


ACP 
error return (cont’d.) 


IE.WLK, H-6 
QIO$ function 
closing a file, H-3 
creating a file, H-2 
deleting a file, H-3 
extending a file, H-3 
opening a file, H-3 
using, H-2 
QIO$ interface, H-1 
Action routine, 7-5 
calling, 7-5 
using, 7-6 
ALUN$ directive summary, F-1 
Ancillary control processor 
See ACP 
ANSI tape standard, G-1 
Append file open function, 2-14 
.ASCPP routine 
converting UIC to binary, 4-7 
.ASLUN routine 
assigning LUN, 4-11, 4-16 
ASSIGN command 
in logical name translation, 4-9 
AST 
service routine, 2-42 
Asynchronous system trap 
See AST 
Attribute buffer 
F11ACP 
address, H-9 
Attribute list 
F11ACP, H-7 
Attribute size, H-8 
Attribute type 
F11ACP, H-7 
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Attribute type 
F11ACP (cont’d.) 


file characteristic, H-7 
file name, H-8 

file owner, H-7 

file protection, H-7 
file type, H-8 
placement control, H-8 
read file header, H-8 
record I/O area, H-7 
revision number, H-8 
statistics block, H-8 
version number, H-8 


B 


Binary to ASCII conversion 
UIC, 4-8 
Blank 
ignoring in command line, 7-8 
Block 
locking, 2-16, 2-43 
enable, 2-15 
F11ACP, H-10, H-12 
logical, 5-2 
unlocking, 2-44 
virtual, 5-2 
Block access 
initialization, 2-11 
READ$ macro, 2-11 
WRITE$ macro, 2-11 
Block boundary, 2-6 
crossing 
record attribute, 3-9 
fixed-length record 
PUT$ macro, 3-27 
FSR block buffer, 3-26 
variable-length record 
PUT$ macro, 3-27 
Block buffer 
initializing FDB, 2-17 
pool space 
FSR, 2-36 
Block I/O, 2-9, 2-10 
block size, 2-12 
buffer, 2-12 
completion event flag, 2-12 
I/O status block, 2-12 
operation, 1-8 
FD.RWM parameter, 3-6 
request 
record attribute, 3-9 
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Block size 
block I/O, 2-12 
override, 3-10 
resetting 
CLOSE$ macro, 2-18 
Block tape 
override size, 2-18 
Buffer 
attribute 
address, H-9 
count 
multiple, 2-18 
multiple, 2-18 
count, 3-10 
type, 2-18 
pool space 
FSR, 2-36 
specifying number, 2-19 
task record, 3-20 
locate mode, 3-26 
PUT$ macro, 3-26 
Buffer boundary 
locate mode, 3-22 
Buffer count 
default, 2-19 
Buffer descriptor 
task, 3-10 
Buffer flush routine, 4-28 
Buffer FSR block 
locate mode, 3-21 
space allocation, 2-19 
Buffering 
big, 1-12 
multiple 
performance, 1-12 
record I/O, 1-11 


C 


Carriage control, 2-6, 2-7 
record attribute, 3-9 
word 

record attribute, 3-9 

CCML$ macro, 6-12 

Checksum value, 5-5 

CLOSE$ 


example of CLOSE$ macro, 5-10 


CLOSE$ example, 5-10 
CLOSE$ macro, 3-1 

file processing, 3-17 

completion, 2-8 


CLOSE$ macro (cont’d.) 
format 


file processing, 3-18 
resetting 
block size, 2-18 
Command file 
closing, 6-12 
resetting scan macro, 6-11 
Command line 
ignoring blanks and tabs, 7-8 
parsing, 7-1 
processing, 6-1 
Command String Interpreter 
See CSI 
Control task tape, G-9 
Conversion 
UIC 
ASCII /binary, 4-7 
SI, 6-1 
expanding file specification, 6-18 
initializing control block, 6-18 
parsing file specification, 6-18 
CSI$1 macro 
command syntax analyzer, 6-18 
CSI$2 macro 
command semantic parser, 6-19 
initializing control block, 6-18 
parsing file specification, 6-18 
CSI$4 macro 
command semantic parser, 6-21 
expanding file specification, 6-18 
CSI$ macro, 6-14 
CSI$ND macro, 6-22 
defining end of descriptor table, 6-29 
CSI$SV macro, 6-22 
creating switch value descriptor table 
entry, 6-27 
CSI$SW macro, 6-22 
creating switch descriptor table entry, 6-22 
CSI control block 
bit values definition, 6-14 
offsets definition, 6-14 
CSI macro 
switch definition, 6-22 
CSI routine, 6-13 
CSI run-time macros, 6-18 
-CTRL routine 
control device, 4-27 
tape, 5-7 


D 


Data format 
ANSI tape, 1-8 
file device, 1-6 
Data-set descriptor, 2-27 
address 
initialization, 2-14 
as data structure, 1-5 
definition, 1-3 
general description, 1-5 
OFNB$x macro, 3-15 
pointer 
definition, 1-3 
pointer file-open, 2-13 
pointer initialization, 2-14 
specifying, 2-26 
Deaccess lock 
F11ACP, H-10 
$DEBUG, 7-2 
Debug routine, 7-6 
DECtape file structure, 5-1 
Default Filename Block 
See DFNB 
DELET$ macro, 3-2, 3-38 
Device control routine, 4-27 
Device information 
.PRSDV routine, 4-15 
Device name 
string descriptor, 2-27 
Device name field, 2-32 
DFENB, 2-29, 3-15 
as data structure, 1-5 
definition, 1-3 
FNBLK$ macro, 2-29 
OFNB$x macro, 3-15 
specifying, 2-26 
Directive summary 
I/O related, F-1 
Directory 
file, 5-2 
identification information 
.-PARSE routine, 4-13 
.PRSDI routine, 4-15 
structure, 5-3 
Directory entry 
deleting 
-REMOV routine, 4-19 
inserting 
-ENTER routine, 4-19 
locating 
.FIND routine, 4-16 
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Directory entry (cont’d.) 
routine, 4-16 
Directory identification 
FNB (F11ACP), H-11 
Directory string 
default 
read, 4-3 
write, 4-3 
routine 
default, 4-3 
Directory string descriptor, 2-27 
Disk file structure, 5-1 
.DLFNB routine 
deleting file by filename block, 4-26 


E 


End-of-file label 

tape, G-8 
End-of-file READ$ macro, 3-33 
End-of-tape handling, G-9 
End-of-volume label 

tape, G-8 
-ENTER routine 

inserting directory entry, 4-19 
Error code 

block locking, 2-45 

file operations, K-1 

IE.IFC, 2-46 

IE.LCK, 2-45, 2-46 

IE.ULK, 2-46 

IE.WAC, 2-45 

shared file, 2-45 
Error return 

ACP, H-3 

GCMLD$ macro, 6-6 
Error routine 

file macro, 3-2 
Event flag 

I/O coordination, 2-40 

I/O synchronization, 3-10 
.EXPLG module 

logical name expansion, 4-15 
Extend control parameter 

F11ACP, H-9 
Extension default, 2-19 
-EXTND routine 

extending file, 4-24 


F 


F.ACTL field 
number of retrieval pointers, A-8 
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F.ALOC field 
number of blocks allocated for extend, 
A-6 
F.BBFS field 
block buffer size, A-7 
F.BDB field 


block buffer descriptor block address, A-7 


F.BGEC field 

big-buffer block count, A-7 
F.BKDN field 

AST service routine address, A-6 
F.BKDS field 

block I/O buffer descriptor, A-5 
F.BKEF field 

block I/O event flag, A-7 
F.BKP1 field 

FCS internal control bits, A-7 
F.BKST field 

1/O status block address, A-6 
F.BKVB field 

user virtual block number, A-7 
F.CHR field 

volume characteristics byte, A-8 
F.CNTG field 

number of blocks to be allocated, A-6 
F.DFNB field 

default filename block pointer, A-7 
F.DSPT field 

data-set descriptor pointer, A-7 
F.EFBK field 

end-of-file block number, A-5 
F.EFN field 

record I/O event flag, A-7 
F.EOBB field 

end-of-block buffer, A-6 
F.ERR+1 field 

F.ERR extension, A-7 
F.ERR field 

error return code byte, A-7 
F.EXT field 

FDB extension address, A-8 
F.FACC field 

file ‘access byte, A-6 
F.FFBY field 

first free byte in last block, A-5 
F.FLG field 

flag byte, A-8 
F.ENB field 

filename block offset, A-8 
F.HIBK field 

highest allocated virtual block number, 

A-4 


F.LUN field 

FDB, 4-16 

LUN for FDB, A-6 
F.MBC1 field 

number of buffers in use, A-7 
F.MBCT field 

number of multiple buffers, A-7 
F.MBFG field 

multibuffer flag word, A-7 
F.NRBD field 

next record buffer descriptor, A-5 
F.NREC field 

address of next record in block, A-6 
F.OVBS field 

override block buffer size, A-6 
F.RACC field 

record access byte, A-5 
F.RATT field 

record attribute byte, A-4 
F.RCNM field 

random access record number, A-6 
F.RCTL 

device characteristic byte 

-PARSE routine, 4-12 

F.RCTL field 

device characteristics byte, A-5 
F.RSIZ field 

record-size word, A-4 


F.RTYP field 

record-type byte, A-4 
F.SEQN field 

sequence number, A-8 
F.STBK field 


statistics block address, A-6 
F.URBD field 

user record buffer descriptor, A-5 
F.VBN field 

virtual block number, A-7 
F.VBSZ 

device buffer size word 

-PARSE routine, 4-12 

F.VBSZ field 

device buffer size word, A-7 
FA.DLK value 

not lock file, 2-16 
FA.EXL value 

block locking, 2-16 
FA.LKL value 

block locking, 2-16 
FA.NSP value 

opening file no superseding, 3-17 


FA.POS value 
file position on close, 2-15 
FA.RWD value 
rewinding on close or open, 2-15 
FA.SHR value 
opening file shared access, 3-17 
FA.TMP value 
opening temporary file, 3-17 
FCS, 1-1 
data structure 
general, 1-5 
file access method, 1-6 
I/O macro, 2-1 
important characteristic, 1-4 
library options, L-1 
library symbols, I-1 
macro 
FDB information, 2-2 
-MCALL directive, 2-2 
term definitions, 1-2 
with Task Builder, 1-1 
FCS.OBJ FCS library, L-1 
FCS impure area, 2-35 
FCSMBF.OB]J FCS library, L-1 
FCSMTA.OBJ FCS library, L-1 
FCSRES routines, 1-21 
-FCTYP routine 
assembly parameters, L-1 
FD.BLK parameter 
record attribute, 2-6 
block boundary crossing, 3-9 
FD.CR parameter 
record attribute, 2-6 
line-feed character, 3-9 
FD.FTN parameter, 3-9 
FD.INS parameter 
sequential file, 2-10 
sequential mode, 3-6, 3-9 
FD.PLC parameter 
locate mode, 2-10, 3-6, 3-9 
move mode, 2-10 
FD.PRN parameter 
record attribute, 2-6 
carriage-control word, 3-9 
FD.RAH parameter 
read-ahead operation, 3-11 
FD.RAH value 
read-ahead, 2-19 
FD.RAN parameter 
random access, 2-10, 3-9 
random record I/O, 3-6 
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FD.RTN 
record attribute, 2-6 
FD.RWM parameter 
block I/O operation, 3-6 
record access, 2-10 
record attribute process with block I/O, 
3-9 
FD.WBH parameter 
write-behind operation, 3-11 
FD.WBH value 
write behind, 2-19 
FDAT$A macro, 2-5 
FDATS$R macro, 2-20 
FDB, 2-3 
address 
run-time macro, 2-23 
allocating file block, 2-8 
as data structure, 1-5 
block I/O, 2-9 
block locking, 2-16 
block size 
resetting, 2-18 
carriage control, 2-7 
definition, 1-2 
description, 1-5 
extension 
logical name translation, 4-14 
F.LUN field, 4-16 
F.xxxx field, A-4 
file identification, 3-10 
GET$ macro, 3-20 
initialization, 2-3 
initializing block access, 2-20 
initializing block buffer, 2-17, 2-20 
initializing block buffer size, 2-17 
initializing file attribute, 2-5, 2-20 
initializing file-open section, 2-13, 2-20 
initializing record access, 2-9, 2-20 
initial values, 2-1 
largest record size, 2-8 
LUN specification, 3-10 
macro global symbol, 2-24 
macro local symbol, 2-25 
macro run-time exceptions, 2-21 
macro run-time initialization, 2-20 
multibuffering, 2-18 
multibuffering type, 2-18 
offset 
global/local, 2-24 
OPEN$x macro requirement, 3-8 
PUT$ macro operation, 3-25 
record I/O, 2-9 
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FDB (cont’d.) 


record size, 3-9 
sequence number field, 2-7 
space allocation, 2-5 
WRITE$ macro, 3-36 
FDBDF$ macro 
FDB space allocation, 2-5 
FDBF$A macro, 2-17 
example of FDBF$A macro, 2-20 
FDBF$R macro, 2-20 
FDBK$A 
example of FDBK$A macro, 2-13 
FDBK$A macro 
block access initialization, 2-11 
record access 
block I/O, 2-11 
FDBK$R macro 
initializing block access, 2-20 
FDOP$A macro, 2-13 
example of FDOP$A macro, 2-16 
FDOP$R macro 
initializing file-open section, 2-20 
FDRC$A macro, 2-9 
example of FORC$A macro, 2-10 
FDRC$R macro 
initializing record access, 2-20 
File 
access method 
FCS, 1-6 
attribute size (F11ACP), H-8 
closing, 3-17 
current command, 6-12 
indirect command, 6-11 
temporary, 3-12 
creating 
FO.WRT value, 3-16 
temporary, 3-12 
temporary mark for deletion, 3-13 
delete routine, 4-26 
deleting, 3-38 
deleting routine, 4-26 
device 
data format, 1-6 
directory, 5-2 
extending, routine, 4-24 
extending WRITE$ macro, 3-35 
extension 
default, 2-19 
default size, 2-9 
size, 2-8 
virtual block, 2-9 
I/O coordination, 2-39 


File (cont’d.) 
I/O status block, 2-41 
identification in FNB (F11ACP), H-11 
index, 5-3 
intializing 
record access, 2-20 
locking, 2-15 
marking 
for deletion, 3-13 
name block 
See FNB 
name block pointer, H-11 
name in FNB (F11ACP), H-11 
no locking on close, 2-16 
opening 
append, 2-14 
by filename block, 3-14 
by ID, 3-13 
for append FO.APD value, 3-17 
for file access, 3-16 
for modifying, 3-17 
for read, 3-16 
for shared access FA.SHR value, 3-17 
for updating and extending, 3-17 
for write FO.WRT value, 3-16 
lock on close, 2-15 
modify, 2-14 
no supersede, 2-14, 3-16, 3-17 
on LP for printing, 8-2 
processing, 3-4 
read access, 2-14 
shared access, 2-14 
tape position, 2-15 
temporary, 2-14, 3-12 
temporary FA.TMP value, 3-17 
temporary mark for deletion, 3-13 
update, 2-14 
write access, 2-14 
opening by ID, 2-32 
operation 
multiple, 5-7 
single, 5-7 
position 
by byte, 2-10 
on closing, 2-15 
random I/O, 2-19 
renaming, 4-23 
sequenced, 2-6 
reading, 2-7 
writing, 2-7 
sequence number, 2-7 
shared access, 1-13 


File (cont’d.) 
space preallocation, 2-19 
specification 
definition, 1-3 
specifying 
within program, 2-26 
truncating routine, 4-25 
truncation, 2-10 
type FNB (F11ACP), H-11 
version number in FNB (F11ACP), H-11 
window pointer number, 2-16 
File access 
optimizing, 2-32 
File attribute 
initializing, 2-5 
initializing run-time, 2-20 
specifying tape, G-16 
File block 
access initialization, 2-11 
access initializing run-time, 2-20 
allocation, 2-8 
buffer initialization, 2-17 
run time, 2-20 
locking, 2-16 
File characteristic 
system-controlled characteristic 
SC.BAD, C-4 
system-conirolled characteristic 
SC.MDL, C-4 
user-controlled 
UC.CON 
contiguous file, C-4 
UC.DLK 
file improperly closed, C-4 
File control routine, 4-1 
File Control Services 
See FCS 
File Descriptor Block 
See FDB 
File header block, 5-4 
format, C-1 
H.XXXX field, C-1, C-2 
header area 
file characteristics, C-4 
file owner information, C-3 
file protection code, C-3 
I.XXXX field, C-2 
identification area, C-4 
creation date, C-5 
creation time, C-5 
expiration date, C-5 
file name, C-4 
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File header block 
identification area (cont’d.) 
file type, C-4 
file version number, C-4 
revision date, C-4 
revision number, C-4 
revision time, C-4 
M.XXXX field, C-2 
map area, C-5 
tape, G-9 
File header label 
ANSI, 5-5 
tape, G-4 
HDRI1, G-4 
HDR2, G-5 
HDR3, G-5 
File identification, 5-4 
FDB, 3-10 
field, 2-32 
File Identification Block 
F11ACP, H-7 
File identifier processing 
by Files-11 
tape, G-7 
File label 
tape, G-1 
File macro, 3-1 
access privileges, 3-4 
error routine, 3-2 
File name 
PARSE routine, 4-14 
.PRSEN routine, 4-16 
tape 
Radix—50 conversion, 4-18 
Filename block 
See also FNB 
default, 2-29, 3-15 
initialization, 2-14 
default directory information 
.GTDID routine, 4-20 
default file-open, 2-13 
default OFNB$x macro, 3-15 
deleting file, 4-26 
directory information 
.GTDIR routine, 4-19 
initializing, 2-33 
manually, 2-34 
local offset definition, 2-31 
N.DID field 
-PARSE routine, 4-13 
N.DVNM field, 4-16 
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Filename block (cont’d.) 
N.NEXT word 


-PARSE routine, 4-15 
N.STAT word 
-PARSE routine, 4-15 
NBOF$L macro, 2-31 
NMBLK$ macro, 2-29 
OPENS$x macro, 2-33 
opening file by, 3-14 
.PARSE routine 
N.DID field, 4-13 
N.FID field, 4-13 
tape, 4-11 
routine, 4-8, 4-19 
specifying 
default, 2-26 
Filename string descriptor, 2-27 
File number, 5-4 
File operation 
error codes, K-1 
File owner word, 4-6 
reading, 4-7 
writing, 4-7 
File pointer routine, 4-21 
File position 
save, 4-22 
to byte 
.POINT routine, 4-21 
to record 
-POSRC routine, 4-22 
File processing 
completion CLOSE$ macro, 2-8 
File protection word, 4-5, 4-6 
File read-ahead FD.RAH parameter, 3-11 
File record 
attribute, 2-6 
File rename routine, 4-23 
Files—11 structure, 5-1 
File sequence number, 5-4 
File specification 
device, 1-15 
magnetic tape, 1-17 
-PRSDV routine, 4-15 
directory, 1-15 
magnetic tape, 1-17 
.PRSDI routine, 4-15 
dynamic processing 
SYSLIB, 2-32 
generation, 1-18 
logical name 
expanding, 4-10 
merging, 4-10 


File specification 
logical name (cont’d.) 
parsing, 4-10 
magnetic tape, 1-17 
name, 1-16 
quoted string 
magnetic tape, 1-18 
syntax description, 1-14 
type, 1-16 
unit 
-PRSDV routine, 4-15 
version, 1-16 
magnetic tape, 1-18 
File Storage Region 
See FSR 
File structure, 5-1 
tape, G-8 
user, 5-2 
virtual blocks, 5-2 
File trailer label 
tape, G-8 
File type 
.PARSE routine, 4-14 
.PRSFN routine, 4-16 
File version 
.PARSE routine, 4-14 
.PRSFN routine, 4-16 
.FIND routine 
locating directory entry, 4-16 
FINIT$ macro 
FSR initialization run-time, 2-37 
.FINIT routine 
initializing before .PARSE routine, 4-11 
Fixed-length record 
PUT$ macro block buffer, 3-27 
Fixed-length record PUT$ macro block 
boundary, 3-27 
Flush buffer routine, 4-28 
.FLUSH routine 
flushing buffer, 4-28 
FNB 
definition, 1-2 
F11ACP, H-11 
directory identification, H-11 
file identification, H-11 
file name, H-11 
file type, H-11 
file version number, H-11 
pointer, H-11 
status word, H-11 
wildcard context, H-11 
N.XXXX field, B-3 


FO.APD value 
opening file for appending, 3-17 
FO.MFY value 
opening file for modifying, 3-17 
FO.RD value 
opening file for reading, 3-16 
FO.UPD value 
opening file for updating and extending, 
3-17 
FO.WRT value 
opening file for writing and creating, 3-16 
FORTRAN carriage-control 
record attribute, 3-9 
FSR 
as data structure, 1-5 
block buffer 
block boundary, 3-26 
locate mode, 3-21, 3-26 
pool space, 2-36 
space allocation, 2-19 
definition, 1-3 
general description, 1-6 
increasing size 
FORTRAN, 2-39 
MACRO-11, 2-38 
initalization FINIT$ macro, 2-37 
initialization FSRSZ$ macro, 2-35 
initializing, 2-35 
record I/O, 2-35, 2-36 
record I/O multibuffering, 2-36 
$$FSR1 program section, 1-6 
$$FSR2 program section 
default UIC, 4-4 
file owner word, 4-6 
file protection word, 4-5 
general description, 1-6 
FSRSZ$ macro 
FSR initialization, 2-35 


G 


GCML, 6-1, 6-3 
control block 
allocating, 6-3 
defining bit values, 6-5 
defining offsets, 6-5 
initializing, 6-3 
routine 
run-time error, 6-9 
use, 6-13 
GCML$ macro, 6-9 
GCMLB$ macro, 6-3 
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GCMLD$ macro, 6-5, 6-6 
GET$ macro, 1-9, 3-1 
example of GET$ macro, 3-19 
FD.RWM parameter 
record I/O, 2-10 
FDB 
file processing, 3-20 
file processing, 3-18 
locate mode, 3-21 
move mode, 3-21 
format 
file processing, 3-19 
GETS$R macro, 3-1 
file processing 
read logical record random mode, 
3-22 
GET$S macro, 3-1 
file processing 
read logical record sequential mode, 
3-23 
Get command line macro 
See GCML 
- Global symbol 
FDB macro, 2-24 
GLUNS$ directive summary, F-1 
GMCR$ directive summary, F-1 
.GTDID routine, 4-19 
default directory information, 4-20 
.GTDIR routine, 4-19 
inserting directory information, 4-19 


H 


H.CKSM offset 

checksum word, C-3 
H.FLEV offset 

structure level, C-1 
H.FNUM offset 

file number, C-1 
H.FOWN offset 

offset to file owner, C-1 
H.FPRO offset 

file protection code, C-1 
H.FSEQ offset 

file sequence number, C-1 
H.IDOF offset 

header area, C-1 
H.MPOF offset 

map area offset, C-1 
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H.PROG offset 
member number, C-1 
H.PROJ offset 
group number, C-1 
H.SCHA offset 
system-controlled file characteristics, C-1 
H.UCHA offset 
user-controlled file characteristics, C-1 
H.UFAT offset 
user file attributes, C-1 
Header area, 5-4 
file header block, C-3 
file characteristics, C-4 
file number, C-3 
file owner information, C-3 
file protection code, C-3 
file sequence number, C-3 
identification area, C-3 
map area offset, C-3 
structure level, C-3 
user file attributes, C-4 
Header block 
file, 5-4 


I.CRDT offset 

creation date, C-2 
I.CRTI offset 

creation time, C-2 
I.EXDT offset 

expiration date, C-2 
I.FNAM offset 

identification area, C-2 
IFTYP offset 

file type, C-2 
IFVER offset 

file version number, C-2 
I.RVDT offset 

revision date, C-2 
ILRVNO offset 

revision number, C-2 
ILRVTI offset 

revision time, C-2 
1/O 

block operation, 1-8 

data-transfer mode, 1-10 

directive summary, F-1 

function support 

F11ACP, H-1 
MTAACP, H-2 
locate mode, 1-10, 1-11 


I/O (cont’d.) 
move mode, 1-10 
preparation 
FCS macro, 2-1 
record 
big buffering, 1-12 
multibuffering, 1-11 
record operation, 1-8 
synchronization, 1-8 
I/O coordination 
event flag, 2-40 
file operation, 2-39 
I/O function 
summary 
FI1ACP, H-12 
MTAACP, H-14 
1/O macro 
AST service routine, 2-42 
FCS, 2-1 
FDB, 2-2 
I/O program example, J-1 
1/O status block 
block I/O, 2-12 
defined in task, 2-42 
file I/O, 2-41 
1/O synchronization event flag, 2-17, 3-10 
I/O wait for completion block I/O, 3-36 
Identification area, 5-4 
file header block, C-4 
creation date, C-5 
creation time, C-5 
expiration date, C-5 
file name, C-4 
file type, C-4 
file version number, C-4 
revision date, C-4 
revision number, C-4 
revision time, C-4 
IE.ABO error return 
ACP, H-3 
IE.ALC error return 
ACP, H-3 
IE.ALN error return 
ACP, H-3 
IE.BAD error return 
ACP, H-3 
IE.BDR error return 
ACP, H-4 
IE.BTP error return 
ACP, H-4 
JE.BVR error return 
ACP, H-4 


IE.BYT error return 
ACP, H-4 
IE.CKS error return 
ACP, H-4 
IE.CLO error return 
ACP, H-4 
IE.DFU error return 
ACP, H-4 
IE.DUP error return 
ACP, H-4 
TE.EOF error return 
ACP, H-4 
IE.HFU error return 
ACP, H-4 
IE.IFC error return 
ACP, H-4 
IE.IFU error return 
ACP, H-4 
IE.LCK error return 
ACP, H-5 
IE.LUN error return 
ACP, H-5 
IE.NOD error return 
ACP, H-5 
IE.NSF error return 
ACP, H-5 
IE.OFL error return 
ACP, H-5 
IE.PRI error return 
ACP, H-5 
IE.RER error return 
ACP, H-5 
IE.SNC error return 
ACP, H-5 
IE.SPC error return 
ACP, H-5 
IE.SQC error return 
ACP, H-5 
TE.WAC error return 
ACP, H-5 
IE.WAT error return 
ACP, H-5 
IE.WER error return 
ACP, H-6 
IE.WLK error return 
ACP, H-6 
Index file, 5-3 
format, E-1 
IO.ACE function 
F11ACP, H-13 
MTAACP, H-14 
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IO.ACP function 
MTAACP, H-16 
IO.ACR function 
F11ACP, H-13 
MTAACP, H-14 
IO.ACW function 
F11ACP, H-13 
MTAACP, H-14 
IO.APV function 
MTAACP, H-16 
IO.CRE function 
F11ACP, H-12 
MTAACP, H-15 
IO.DAC function 
F11ACP, H-13 
MTAACP, H-15 
IO.DEL function 
F11ACP, H-12 
IO.ENA function 
F11ACP, H-13 
MTAACP, H-14 
IO.EXT function 
F11ACP, H-13 
IO.FNA function 
F11ACP, H-13 
MTAACP, H-14 
IO.RAT function 
F11ACP, H-13 
MTAACP, H-16 
IO.RNA function 
F11ACP, H-13 
IO.RVB function 
F11ACP, H-14 
MTAACP, H-15 
IO.ULK function 
F11ACP, H-13 
IO.WVB function 
F11ACP, H-14 
ISTAT$ macro, 7-1, 7-2 


K 


Keyword recognition 
transition table, 7-9 


L 


Line-feed character 
record attribute, 3-9 

Local symbol 
FDB macro, 2-25 

Locate mode, 1-10, 1-11, 2-10 
file processing, 3-26 
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Locate mode (cont’d.) 


FSR block buffer, 3-26 
GET$ macro, 3-18, 3-21 
PUTS macro, 3-24, 3-27 
record attribute, 3-9 
task record buffer, 3-26 
Logical block, 5-2 
file device, 1-7 
Logical name, 1-19 
specifying, 1-20 
translation, 4-8 
ASSIGN command, 4-9 
expanding file specification string, 
4-10 
FDB extension, 4-14 
iterative, 4-9 
merging file specification, 4-10 
name expansion 
-EXPLG module, 4-15 
parse file specification, 4-10 
-PARSE routine 
device and unit, 4-12 
process, 4-10 
-PRSDV routine, 4-15 
use, 1-20 
Logical unit number 
See LUN 
LUN 
assigning with .ASLUN routine, 4-16 


M 


M.CTSZ offset 
retrieval pointer block count field size, 
C-2 
M.EFNU offset 
extension file number, C-2 
M.EFSO offset 
extension file sequence number, C-2 
M.ERVN offset 
extension relative volume number, C-2 
M.ESQN offset 
map area, C-2 
M.LBSZ offset 
retrieval pointer logical block number field 
size, C-2 
M.MAX offset 
available retrieval pointer words, C-2 
M.RTRV offset 
retrieval pointer start, C-2 


M.USE offset 

retrieval pointer word count, C-2 
Macro global symbol, 2-24 
Macro local symbol, 2-25 
Macro run time 

exceptions, 2-21 

FDB address, 2-23 

initialization, 2-20 
MAG, G-9 

task error messages, G-14 
Map area, 5-5 

file header block, C-5 
.MARK routine 

save file position, 4-22 
Master File Directory 

See MFD 
.MCALL directive, 2-2 
MED, 5-2 
Move mode, 1-10 

GET$ macro, 3-18, 3-21 

PUT$ macro, 3-24, 3-26 
.MRKDL routine 

marking temporary file for deletion, 4-26 
Mutifile operation, 5-7 


N 


N.ANM1 field 

ANSI filename string, B-5 
N.ANM2 field 

remainder of ANSI filename string, B-5 
N.DID field 

directory identification, B-3 

.PARSE routine, 4-13 
N.DVNM field, 4-16 

ASCII device name, B-3 

ASCII tape device name, B-5 
N.FID field 

file identification, B-3, B-5 

.FIND routine, 4-16 

PARSE routine, 4-13 
N.FNAM field 

file name, B-3 
N.FTYP field 

file type, B-3 
N.FVER field 

file version number, B-3 

tape file version number, B-5 
N.NEXT field 

context for next .FIND, B-3 

tape context for next .FIND, B-5 


N.STAT field 
filename block status word, B-3 
tape filename block status word, B-5 
N.UNIT field 
FNB (tape), B-5 
unit number field, B-3 
NBOF$L macro, 2-31 
NMBLK$ macro 
default filename block, 2-29 
example of NMBLK$ macro, 2-31 


O 


OFID$ macro, 3-1 
OFID$x macro 

file processing, 3-13 
OFNB$ macro, 3-1 
OFNB$x macro 

data-set descriptor, 3-15 

default filename block, 3-15 

file processing, 3-14 
OPEN$ macro, 3-1 

example of OPEN$ macro, 5-10 

file processing, 3-16 
OPENS$R macro 

example of OPEN$R macro, 5-9 

shared access, 1-14 
OPEN$x macro 

file processing, 3-3, 3-8 

format 

file operations, 3-5 

Open file processing, 3-4 
Open file routine 

by filename block, 3-14 

by ID, 3-13 

existing, 3-9 

for access, 3-16 

for modifying, 3-17 

for read, 3-16 

for updating and extending, 3-17 

new, 3-9 

no supersede, 3-16, 3-17 
OPNS$ macro, 3-1 
OPNS$R macro 

shared access, 1-13 
OPNS$x macro 

file processing, 3-11 
OPNT$D macro, 3-13 
OPNT$ macro, 3-1 
OPNT$W macro 

file processing, 3-12 
Owner ID field tape, G-2 
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Pp 


.PARSE routine 
device and unit translation, 4-12 
logical name translation, 4-10 
Parser program 
TPARS, 7-12 
processing steps, 7-12 
Placement control F11ACP, H-11 
POINT routine 
file byte position, 2-10 
positioning file to byte, 4-21 
.POSIT routine 
returning record position, 4-23 
-POSRC routine 
positioning file to record, 4-22 
.PPASC routine 
converting UIC to ASCII, 4-8 
PRINT$ macro, 8-1 
error handling, 8-2 
PRINT command, 8-2 
Print function 
opening file on LP, 8-2 
-PRINT routine 
error handling, 8-2 
.PRINT subroutine, 8-2 
Program example I/O, J-1 
Program section 
TPARS, 7-9 
.PRSDI routine 
filling in directory information, 4-15 
.PRSDV routine 
filling in device/unit information, 4-15 
-PRSFN routine 
filling in file name, type, version, 4-16 
PUT$ macro, 1-9, 3-1, 3-26 
FD.RWM parameter 
record I/O, 2-10 
FDB 
file processing, 3-25 
file processing 
locate mode, 3-26 
write logical record, 3-24 
file truncate, 2-10 
fixed-length record, 3-26 
block boundary, 3-27 
block buffer, 3-27 
locate mode, 3-24, 3-27 
move mode, 3-24, 3-26 
no truncate function, 2-10 
sequenced record, 3-24 
task record buffer, 3-26 
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PUT$ macro (cont’d.) 


variable-length record, 3-26 
block boundary, 3-27 
PUT$R macro, 3-1 
example of PUT$R macro, 3-29 
file processing 
write logical record random mode, 
3-28 
random mode 
locate mode execution, 3-29 
PUT$S macro, 3-1 
file processing 
write logical record, 3-29 
sequential mode, 3-29 


Q 


QIO$ 
ACP interface, H-1 
parameter list (F11ACP), H-6 
QIO$ directive summary, F-2 
QIO$ function 
ACP 
closing a file, H-3 
creating a file, H-2 
deleting a file, H-3 
extending a file, H-3 
opening a file, H-3 
using, H-2 
QIO execution routine, 4-23 
QIOWS$ directive summary, F-2 


R 


a 
R.FIX 


file attribute, 2-6 
parameter 
fixed-length records, 3-8 
R.SEQ 
file attribute, 2-6 
parameter 
sequenced records, 3-8 
R.VAR 
file attribute, 2-6 
parameter 
variable-length records, 3-8 
Random access, 2-10 
Random access mode, 3-20 
record attribute, 3-9 
Random I/O, 2-19 
Random mode 
PUT$R macro 
locating mode execution, 3-29 


Random mode (cont’d.) 
writing logical record, 3-28 

RCML$ macro, 6-11 

RCST$ directive summary, F-3 

RCVD$ directive summary, F-3 

RCVX$ directive summary, F-3 

-RDFDR routine 


reading $$FSR2 default directory string, 


4-3 
-RDFPP routine 
reading $$FSR2 default file protection 
word, 4-5 
.RDFUI routine 
reading default UIC, 4-4 
Read $$FSR2 
default directory string, 4-3 
READ$ macro, 1-8, 3-1 
block access, 2-11 
end-of-file, 3-33 
example of READ$ macro, 3-32 
FD.RWM parameter 
block I/O, 2-10 
FDB 
file operation, 3-33 
file processing 
reading virtual block, 3-30 
format file processing, 3-30 
virtual block number, 3-31 
Read access function 
F11ACP, H-12 
file open, 2-14 
shared, 1-14 
Read-ahead file processing, 2-19 
Read function 
default UIC, 4-4 
file protection word 
default, 4-5 
logical record file processing, 3-18 
logical record random mode file 
processing, 3-22 
logical record sequential mode, 3-23 
virtual block file processing, 3-30 
Record 
fixed-length 
R.FIX parameter, 3-8 
sequenced 
R.SEQ parameter, 3-8 
variable-length, 1-6 
R.VAR parameter, 3-8 
Record access initialization, 2-9 
Record attribute, 2-6, 3-8 


FD.BLK parameter 
block boundary crossing, 3-9 
FD.CR parameter, 2-6 
line-feed character, 3-9 
FD.FTN parameter, 2-6 
FORTRAN carriage-control, 3-9 
FD.RAN parameter 
random access mode, 3-9 
FD.RPN parameter 
carriage-control word, 3-9 
locate mode, 3-9 
sequential mode, 3-9 
FD.RWM parameter 
process with block I/O, 3-9 
Record buffer task 
locate mode, 3-26 
Record fixed-length PUT$ macro, 3-26 
Record format 
tape, 5-5 
Record 1/O, 2-9, 2-10 
FSR, 2-35, 2-36 
FSRZ 
multibuffering, 2-36 
locate mode 
FD.PLC parameter, 3-6 
macro calls, 2-9 
mode, 1-10 
multibuffering, 1-11 
operation, 1-8 
random 
FD.RAN parameter, 3-6 
synchronization, event flag, 2-17 
Record sequenced PUT$ macro, 3-24 
Record size 
FDB, 3-9 
fixed-length, 2-7 
largest, 2-8 
Record variable-length PUT$ macro, 3-26 
-REMOVE routine 
deleting directory entry, 4-19 
-RENAME routine 
renaming file, 4-23 
-RFOWN routine 
reading $$FSR2 file owner word, 4-7 
$RONLY macro 
state table, 7-2 
Run-time initialization 
FSR FINIT$ macro, 2-37 
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S.HDHD offset 
header area size, C-2 
S.IDHD offset 
identification area size, C-2 
S.MPHD offset 
map area size, C-3 
SC.MDL offset 
bad data block 
user-controlled file characteristic, C-4 
file marked for deletion 
user-controlled file characteristic, C-4 
SDATS$ directive summary, F-3 
SDRC$ directive summary, F-4 
SDRP$ directive summary, F-4 
Security information DELET$ macro, 3-38 
Sequenced mode GET$ operation, 3-19 
Sequential file, 2-10 
Sequential mode 
FD.INS parameter, 3-6 
record attribute, 3-9 
write logical record, 3-29 
Shared access 
file open, 2-14, 3-11 
Shared access file, 1-13 
Single file operation, 5-7 
Size parameter 
FL1ACP, H-9 
SMSG$ directive summary, F-5 
Special character state table, 7-8 
Spooling, 8-1 
.PRINT subroutine, 8-2 
STATE$ macro, 7-1, 7-2 
$STATE program section, 7-2 
State table, 7-1 
arrangement of syntax types, 7-7 
initializing, 7-2 
rejecting transitions, 7-18 
special character, 7-8 
using subexpressions, 7-18 
Statistics block, D-1 
address, 3-11 
Status word 
F11ACP 
FNB, H-11 
Subexpression 
parsing complex command lines, 7-19 
Syntax element 
defining, 7-2 
Syntax state table, 7-7 
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T 


Tab 
ignoring in command line, 7-8 
Table Driven Parse 
See TPARS 
Tape 
ANSI file structure, 5-1 
control task, G-9 
data format, 1-8 
end-of-file label, G-8 
end-of-volume label, G-8 
file header block, G-9 
file processing, 5-5 
file structure, G-8 
fixed-length records, 1-8 
handling end-of-tape, G-9 
owner ID field, G-2 
positioning, G-16 
position to next file, 5-6 
processing example, 5-8 
record format, 5-5 
translation, G-17 
unlabeled, G-15 
block size, G-15 
user file label, G-8 
user volume label, G-3 
variable-length record, 1-8 
volume access, 5-5 
volume label, G-1 
Tape file 
attributes 
specifying, G-16 
header label, G-4 
HDRI1, G-4 
HDR2, G-5 
HDR3, G-5 
identifier processing, G-7 
label, G-1 
Tape position 
file open, 2-15 
Tape read function 
indirect command file, G-19 
Tape standard 
ANSI, G-1 
Task 
spooling print job, 8-1 
Task buffer descriptor, 3-10 
Task record buffer, 3-20 
TPARS 
built-in variable, 7-5 
coding, 7-1, 7-7 
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command line parsing, 7-1 
creating parser program, 7-12 
invoking, 7-11 
macro, 7-1 
options word, 7-12 
programming examples, 7-14 
program section, 7-9 
register usage, 7-11 
state table, 7-1 
subexpression, 7-6 
transition, 7-1 
TRAN$ macro, 7-1, 7-3 
Transition table 
recognition of keyword, 7-9 
.TRNCL routine 
truncating file, 4-25 


U 


UC.CON 
contiguous file 
user-controlled file characteristic, C-4 
UC.DLK 
file improperly closed 
user-controlled file characteristic, C-4 
UFD, 5-2 
UIC, 5-2 
ASCII-binary conversion, 4-7, 4-8 
read/write defaults, 4-4 
Unit information 
.PRSDV routine, 4-15 
Unit number field, 2-32 
Unlabeled tape, G-15 
block size, G-15 
User file attributes 
header area 
file characteristics, C-4 
User File Directory 
See UFD 
User file label 
tape, G-8 
User Identification Code 
See VIC 
User volume label tape, G-3 


V 


Variable-length record block boundary PUT$ 


macro, 3-27 
Virtual block 
file device, 1-7 
file extension, 2-9 


Virtual block number 

READ$ macro, 3-31 

WRITE$ macro, 3-34 
Volume default extend size, 2-9 
Volume label 

tape, G-1 

tape user, G-3 
Volume sets 

rewinding, 5-6 
VRCD$§$ directive summary, F-5 
VRCS$ directive summary, F-5 
VRCX$ directive summary, F-6 
VSDA$ directive summary, F-6 
VSRC$ directive summary, F-7 


W 


WAIT$ macro 
file processing, 3-2 
block I/O completion, 3-36 
format file operations, 3-36 
with READ$ and WRITE$, 3-36 
with READ$ or WRITE$, 3-30 
.WDFPP routine 
writing $$FSR2 default file protection 
word, 4-6 
.WDFR routine 
writing $$FSR2 default directory string, 
4-3 
.WDFUI routine 
writing default UIC, 4-4 
.WFOWN routine, write $$FSR2 file owner 
word, 4-7 
Wildcard 
context (FI1ACP) 
FNB, H-11 
file name, 4-18 
file type, 4-18 
Window pointer number, 2-15, 2-16 
Window size parameter 
F11ACP, H-10 
Write $$FSR2 macro 
default directory string, 4-3 
WRITE$ macro, 1-8, 3-2 
block access, 2-11 
example of WRITE$ macro, 3-35 
extending file, 3-35 
FD.RWM parameter 
block I/O, 2-10 
FDB, 3-36 
file processing, 3-33 
writing virtual block, 3-33 
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format, 3-33 
virtual block number, 3-34 
Write access 
F11ACP, H-12 
file open, 2-14 
shared, 1-13 
Write-behind file processing, 2-19 
Write-behind operation 
FD.WBH parameter, 3-11 
Write default UIC function, 4-4 
Write file protection word function 
default, 4-6 
Write function 
file owner word, 4-7 
Write logical record function 
file processing, 3-24 
random mode, 3-28 
sequential mode, 3-29 
Write virtual block file processing, 3-33 


X 


.XQIO routine 
executing QIO, 4-23 
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READER’S Your comments and suggestions are welcome and will help us in our 
continuous effort to improve the quality and usefulness of our documentation 


COMMENTS and software. 


Remember, the system includes information that you read on your terminal: 
help files, error messages, prompts, and so on. Please let us know if you have 
comments about this information, too. 


Did you find this manual understandable, usable, and well organized? Please make suggestions for 
improvement. 


Did you find errors in this manual? If so, specify the error and the page number. 


What kind of user are you? —— Programmer —_— Nonprogrammer 


Years of experience as a computer programmer /user: 


Name Date 


Organization 


Street 


City State ______ Zip Code 


or Country 
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